Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

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 (25)

Supported targets

Anchor to PropertiesProperties

The Extension API object provides extension metadata for customer account extensions. Access the following properties on the API object 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. For configuration details, see shopify.extension.toml.

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/customer-account-ui-extensions/2025-07/configuration) file.
```
StatefulRemoteSubscribable<Capability[]>
```
editor
Information about the editor where the extension is being rendered. The value is undefined if the extension isn’t rendering in an editor.
```
Editor
```
rendered
Whether your extension is currently rendered to the screen. Shopify may render your extension before it's visible in the UI to pre-render content. Your extension may also continue running after the buyer navigates away so it's immediately available if they return.
```
StatefulRemoteSubscribable<boolean>
```
scriptUrl
The URL of the JavaScript file that powers this 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. For available targets, see the [extension targets overview](/docs/api/customer-account-ui-extensions/2025-07/extension-targets-overview). For configuration details, see [extension targets](/docs/apps/app-extensions/configuration#targets).
```
Target
```
version
The published version of the running extension. 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, and can change without notice because it's not subject to versioning guarantees.

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

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 where the extension is being rendered.

type
Indicates whether the extension is rendering in the checkout editor.
```
'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

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

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

import {

reactExtension,

useApi,

BlockStack,

Text,

} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(

'customer-account.order-status.block.render',

() => <Extension />,

);

function Extension() {

const {extension} = useApi();

const {handle, url} = extension;

return (

<Text>Extension handle: {handle}</Text>

<Text>Extension URL: {url}</Text>

</BlockStack>

);

}

Examples

Read extension metadata

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.

React

import {
  reactExtension,
  useApi,
  BlockStack,
  Text,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

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

  return (
    <BlockStack>
      <Text>Extension handle: {handle}</Text>
      <Text>Extension URL: {url}</Text>
    </BlockStack>
  );
}

TS

import {
  extension,
  BlockStack,
  Text,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const {handle, url} = api.extension;

    const handleText = root.createComponent(
      Text,
      {},
      `Extension handle: ${handle}`,
    );

    const urlText = root.createComponent(
      Text,
      {},
      `Extension URL: ${url}`,
    );

    const stack = root.createComponent(
      BlockStack,
      {},
      [handleText, urlText],
    );

    root.appendChild(stack);
  },
);

Conditionally render by editor type

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.

React

import {
  reactExtension,
  useApi,
  Banner,
} from '@shopify/ui-extensions-react/customer-account';

export default reactExtension(
  'customer-account.order-status.block.render',
  () => <Extension />,
);

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

  if (editorType === 'checkout') {
    return (
      <Banner title="Order confirmation">
        Thank you for your purchase!
      </Banner>
    );
  }

  return (
    <Banner title="Your account">
      Manage your orders and preferences here.
    </Banner>
  );
}

TS

import {
  extension,
  Banner,
} from '@shopify/ui-extensions/customer-account';

export default extension(
  'customer-account.order-status.block.render',
  (root, api) => {
    const editorType = api.extension.editor?.type;

    const banner = root.createComponent(
      Banner,
      {
        title:
          editorType === 'checkout'
            ? 'Order confirmation'
            : 'Your account',
      },
      editorType === 'checkout'
        ? 'Thank you for your purchase!'
        : 'Manage your orders and preferences here.',
    );

    root.appendChild(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.

Anchor to LimitationsLimitations

Extension metadata is read-only. You can't modify the handle, URL, or editor type at runtime.
The editor property is only available when the extension is rendered within an editor context. It may be undefined when the extension runs in a live customer-facing environment.
The url property reflects the extension's current URL, which may differ between local development and deployed environments.

Was this page helpful?