Choose a version:

Extension API

The Extension API lets you read metadata about your extension at runtime, including its handle and URL. Use this API to build dynamic URLs that point to your extension, read editor context when it's available, or log extension details for debugging.

Anchor to Use casesUse cases

Build extension URLs: Use the extension's url property to construct links that point back to your extension or share its location with your backend.
Conditionally render by editor type: Check editor.type to display different content depending on where the extension is rendered.
Log extension details for debugging: Include the extension handle and url in error reports or diagnostic output to identify which extension instance is running.

Support

Targets (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides extension metadata for customer account extensions. Access the following properties on shopify to read your extension's handle, URL, and editor context at runtime.

Anchor to extension extension required: Metadata about the extension, including its target, version, and editor context. Use this to conditionally render content based on where the extension is running.

Extension

Metadata about the running extension, including its API version, target, capabilities, and editor context. Use this to read configuration details or conditionally render content based on where the extension is running.

apiVersion
The API version that was set in the extension config file.
```
ApiVersion
```
capabilities
The allowed capabilities of the extension, defined in your [`shopify.extension.toml`](/docs/api/checkout-ui-extensions/latest/configuration) file.
```
SubscribableSignalLike<Capability[]>
```
editor
Information about the editor where the extension is being rendered. If the value is undefined, then the extension isn't running in an editor.
```
Editor
```
rendered
A Boolean to show whether your extension is currently rendered to the screen. Shopify might render your extension before it's visible in the UI, typically to pre-render extensions that appear on a later step of the checkout. Your extension might also continue to run after the customer has navigated away from where it was rendered. The extension continues running so that your extension is immediately available to render if the customer navigates back.
```
SubscribableSignalLike<boolean>
```
scriptUrl
The URL to the script that started the extension target.
```
string
```
target
The identifier that specifies where in Shopify's UI your code is being injected. This is one of the targets you've included in your extension's configuration file.
```
Target
```
version
The published version of the running extension target. For unpublished extensions, the value is `undefined`. Don't use this property as a stable identifier in development environments. It becomes available only after the extension is published.
```
string
```

ApiVersion

The supported GraphQL Admin API versions. Use this to specify which API version your GraphQL queries should execute against. Each version includes specific features, bug fixes, and breaking changes. The `unstable` version provides access to the latest features but may change without notice.

'2023-04' | '2023-07' | '2023-10' | '2024-01' | '2024-04' | '2024-07' | '2024-10' | '2025-01' | '2025-04' | 'unstable' | '2025-07' | '2025-10' | '2026-01' | '2026-04'

SubscribableSignalLike

Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends `ReadonlySignalLike` with deprecated fields that are still supported for backwards compatibility.

current
The current value of the signal. Equivalent to `.value`, accessing this property subscribes to changes when used in a reactive context.
```
T
```
destroy
Cleans up the subscription and releases any resources held by this signal. After calling `destroy()`, the signal stops receiving updates from the main thread.
```
() => Promise<void>
```
subscribe
Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value.
```
(fn: (value: T) => void) => () => void
```
value
The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup.
```
T
```

Capability

The capabilities an extension has access to. * `api_access`: The extension can access the Storefront API. * `network_access`: The extension can make external network calls. * `block_progress`: The extension can block a buyer's progress and the merchant has allowed this blocking behavior. * `collect_buyer_consent.sms_marketing`: The extension can collect buyer consent for SMS marketing. * `collect_buyer_consent.customer_privacy`: The extension can register buyer consent decisions that will be honored on Shopify-managed services. * `iframe.sources`: The extension can embed an external URL in an iframe.

'api_access' | 'network_access' | 'block_progress' | 'collect_buyer_consent.sms_marketing' | 'collect_buyer_consent.customer_privacy' | 'iframe.sources'

Editor

Information about the editor environment when an extension is rendered inside the checkout editor. The value is `undefined` when the extension is not rendering in an editor.

type
Indicates whether the extension is rendering in the [checkout editor](/docs/apps/checkout). Always `'checkout'`.
```
'checkout'
```

Target

selectedSuggestion
```
AddressAutocompleteSuggestion
```

AddressAutocompleteSuggestion

formattedAddress
The address object used to auto-populate the remaining address fields. If this value is returned for every suggestion, then the `purchase.address-autocomplete.format-suggestion` extension target is not needed.
```
AutocompleteAddress
```
id
A textual identifier that uniquely identifies an autocomplete suggestion or address. This identifier may be used to search for a formatted address.
```
string
```
label
The address suggestion text presented to the buyer in the list of autocomplete suggestions. This text is shown to the buyer as-is. No attempts will be made to parse it.
```
string
```
matchedSubstrings
A list of substrings that matched the original search query. If `matchedSubstrings` are provided, then they will be used to highlight the substrings of the suggestions that matched the original search query.
```
MatchedSubstring[]
```

AutocompleteAddress

An address object used to auto-populate the address form fields. All fields are optional

address1
The first line of the street address, including the street number and name. The value is `undefined` if the buyer hasn't entered an address yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```
address2
The second line of the buyer's address, such as apartment number, suite, or unit. The value is `undefined` if the buyer didn't provide a second address line. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```
city
The city, town, or village of the address. The value is `undefined` if the buyer hasn't entered a city yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```
company
The buyer's company name. The value is `undefined` if the buyer didn't enter a company or the store doesn't collect company names. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```
countryCode
The two-letter country code in [ISO 3166 Alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) format. The value is `undefined` if the buyer hasn't selected a country yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
CountryCode
```
latitude
The latitude coordinates of the buyer. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
number
```
longitude
The longitude coordinates of the buyer. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
number
```
provinceCode
The province, state, prefecture, or region code of the address. The format varies by country. The value is `undefined` if the buyer hasn't selected one yet or the country doesn't have provinces. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```
zip
The postal code or ZIP code of the address, used for mail sorting and delivery routing. The value is `undefined` if the buyer hasn't entered one yet or the country doesn't use postal codes. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).
```
string
```

CountryCode

'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PS' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'ZZ'

MatchedSubstring

length
The length of the matched substring in the suggestion label text.
```
number
```
offset
The start location of the matched substring in the suggestion label text.
```
number
```

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const {handle, url} = shopify.extension;

return (

<s-stack direction="block" gap="base">

<s-text>

Extension handle: {handle}

</s-text>

<s-text>Extension URL: {url}</s-text>

</s-stack>

);

}

Examples

Description

Access the extension's handle and URL at runtime to display or log them. This example reads `shopify.extension.handle` and `shopify.extension.url` and renders them in text components.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const {handle, url} = shopify.extension;

  return (
    <s-stack direction="block" gap="base">
      <s-text>
        Extension handle: {handle}
      </s-text>
      <s-text>Extension URL: {url}</s-text>
    </s-stack>
  );
}

Description

Display different content based on the editor type where the extension is rendered. This example checks `shopify.extension.editor?.type` and shows a context-specific banner accordingly.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const editorType =
    shopify.extension.editor?.type;

  if (editorType === 'checkout') {
    return (
      <s-banner heading="Order confirmation">
        Thank you for your purchase!
      </s-banner>
    );
  }

  return (
    <s-banner heading="Your account">
      Manage your orders and preferences here.
    </s-banner>
  );
}

Anchor to Best practicesBest practices

Use the handle for identification: Reference shopify.extension.handle when logging or communicating with your backend so you can identify which extension is active.
Check editor type defensively: The editor property may be undefined in some contexts. Always use optional chaining (editor?.type) when accessing it.
Don't hardcode extension URLs: Use shopify.extension.url instead of constructing URLs manually. The URL may vary between development and production environments.

Was this page helpful?