Choose a version:

Extension API

The Extension API provides read-only access to metadata about the running extension. Use this API to inspect the current target and API version, check which capabilities are enabled, detect whether the extension is being previewed in the checkout and accounts editor, and check whether the extension is rendered on screen.

Anchor to Use casesUse cases

Display debugging information: Show the active target name and API version during development to verify your extension is running where expected.
Check capabilities before rendering: Test whether a capability like block_progress has been granted, and show a warning in the editor when it's missing.
Detect the editor context: Use the editor property to adjust behavior according to whether the extension is being previewed in the checkout and accounts editor or running in a live checkout.
Defer work until visible: Use the rendered property to detect whether your extension is visible on screen. Shopify might pre-render your extension before the buyer reaches the step where it appears, so you can delay expensive operations until rendered is true.

Support

Targets (33)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides extension metadata for the current checkout. Access the following properties on shopify to read the extension's target, version, capabilities, and editor context. Available to purchase extension targets.

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

Extension

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/configuration) file. * [`api_access`](/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API. * [`network_access`](/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls. * [`block_progress`](/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a customer's progress and the merchant has allowed this blocking behavior. * [`collect_buyer_consent.sms_marketing`](/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect customer consent for SMS marketing. * [`collect_buyer_consent.customer_privacy`](/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register customer consent decisions that will be honored on Shopify-managed services. * [`iframe.sources`](/docs/api/checkout-ui-extensions/configuration#iframe): the extension can embed an external URL in an iframe.
```
Capability[]
```
editor
The information about the editor where the extension is being rendered. If the value is undefined, then the extension is not 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 will 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. If the extension is not capable of rendering UI components, then the value will always be false.
```
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 will be one of the targets you have included in your extension’s configuration file.
```
Target
```
version
The published version of the running extension target. For unpublished extensions, the value is `undefined`.
```
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'

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
```

Anchor to Available Preact hooksAvailable Preact hooks

The following Preact hooks provide a convenience wrapper that makes it easier to perform common tasks without writing your own logic.

Anchor to useExtensionCapability
useExtensionCapability(
capability
)

Returns whether or not a given capability of an extension is granted.

Anchor to useExtensionCapability-parametersParameters

Anchor to capability capability required

Anchor to useExtensionCapability-returnsReturns
boolean

Examples

jsx

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

import {render} from 'preact';

export default function extension() {

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

}

function Extension() {

const {target, apiVersion, version} =

shopify.extension;

return (

<s-stack>

<s-text>

Target: {target}

</s-text>

<s-text>

API version: {apiVersion}

</s-text>

{version && (

<s-text>

Extension version: {version}

</s-text>

)}

</s-stack>

);

}

Examples

Description

Access the current target name, API version, and published version. This example reads `shopify.extension` and displays each metadata field, with the version showing as `undefined` for unpublished extensions.

jsx

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

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

function Extension() {
  const {target, apiVersion, version} =
    shopify.extension;

  return (
    <s-stack>
      <s-text>
        Target: {target}
      </s-text>
      <s-text>
        API version: {apiVersion}
      </s-text>
      {version && (
        <s-text>
          Extension version: {version}
        </s-text>
      )}
    </s-stack>
  );
}

Description

Test whether a specific permission has been granted and detect if the extension is running in the editor. This example checks `block_progress` and renders a warning banner when it isn't enabled.

jsx

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

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

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

function Extension() {
  const canBlockProgress =
    useExtensionCapability('block_progress');
  const editor = shopify.extension.editor;

  if (editor?.type === 'checkout' && !canBlockProgress) {
    return (
      <s-banner tone="warning" heading="Missing permission">
        Enable "block checkout progress" in
        the checkout editor to use this
        extension.
      </s-banner>
    );
  }

  return null;
}

Anchor to Best practicesBest practices

Check capabilities in the editor context: Use shopify.extension.editor alongside useExtensionCapability to surface missing permissions only when the merchant is configuring the extension. This helps merchants fix capability issues before publishing.

Was this page helpful?

Anchor to Use casesUse cases

Supported targets

Supported targets

Anchor to PropertiesProperties

Extension

ApiVersion

Capability

Editor

Target

AddressAutocompleteSuggestion

AutocompleteAddress

CountryCode

MatchedSubstring

Anchor to Available Preact hooksAvailable Preact hooks

Anchor to useExtensionCapabilityuseExtensionCapability(capabilitycapability)

Anchor to useExtensionCapability-parametersParameters

Anchor to useExtensionCapability-returnsReturnsbooleanboolean

Anchor to Best practicesBest practices

Anchor to useExtensionCapability
useExtensionCapability(
capability
)

Anchor to useExtensionCapability-returnsReturns
boolean