---
title: Extension API
description: >-
  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.
api_version: 2025-07
api_name: customer-account-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/extension-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/extension-api.md
---

Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension.

# 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.

### Use 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

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-announcement-)
* [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-)
* [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-item-render-after-)
* [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#cart-line-list-render-after-)
* [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#customer-information-render-after-)
* [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets)
* [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#payments-and-returns-targets)
* [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/payments-and-returns#return-details-render-after-)
* [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-)
* [customer-account.​order.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

### Properties

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.

* **extension**

  **Extension**

  **required**

  Metadata about the extension, including its target, version, and editor context. For configuration details, see [`shopify.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#configuration).

### 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.

  ```ts
  ApiVersion
  ```

* capabilities

  The allowed capabilities of the extension, defined in your \[\`shopify.extension.toml\`]\(/docs/api/customer-account-ui-extensions/2025-07/configuration) file.

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

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

  ```ts
  StatefulRemoteSubscribable<boolean>
  ```

* scriptUrl

  The URL of the JavaScript file that powers this extension target.

  ```ts
  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).

  ```ts
  Target
  ```

* version

  The published version of the running extension. For unpublished extensions, the value is \`undefined\`.

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

```ts
'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.

```ts
'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.

  ```ts
  'checkout'
  ```

### Target

* selectedSuggestion

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

  ```ts
  AutocompleteAddress
  ```

* id

  A textual identifier that uniquely identifies an autocomplete suggestion or address. This identifier may be used to search for a formatted address.

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

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

  ```ts
  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).

  ```ts
  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).

  ```ts
  number
  ```

### MatchedSubstring

* length

  The length of the matched substring in the suggestion label text.

  ```ts
  number
  ```

* offset

  The start location of the matched substring in the suggestion label text.

  ```ts
  number
  ```

Examples

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

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

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

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

  ```js
  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);
    },
  );
  ```

***

## Best 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.

***

## Limitations

* 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.

***