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/customer-account-ui-extensions/latest/configuration) file.
```
SubscribableSignalLike<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 might render your extension before it's visible in the UI, typically to pre-render extensions that will appear on a later page. Your extension might also continue to run after the buyer has navigated away from where it was rendered. The extension continues running so that it's immediately available if the buyer 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 will be one of the [targets](/docs/api/customer-account-ui-extensions/latest/configuration#targets) you have included in your extension’s configuration file. For more information, refer to the [extension targets overview](/docs/api/customer-account-ui-extensions/latest/extension-targets-overview).
```
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' | '2026-07' | '2026-10'

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

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

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.

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>
  );
}

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.

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?