App API
The App API provides read-only access to extension information through the app.extensions() method, enabling discovery of installed extensions and their activation status. The method asynchronously retrieves detailed information including handles, types, and activations across different surfaces.
The method returns a Promise that resolves to an array of ExtensionInfo objects. Each object contains:
handle: The unique identifier for the extensiontype: Either'ui_extension'or'theme_app_extension'activations: Activation records (shape varies by extension type)
The array may be empty if the app has no extensions.
UI extensions have activations with a target field indicating the admin, checkout, customer account or point of sale target.
Theme app extensions have activations representing individual blocks/embeds, each with:
handle: Block/embed filenamename: Display name from block schematarget: Location type ('section','head','body', or'compliance_head')status: Availability status ('active','available', or'unavailable')activations: Array of theme-specific placements withtargetandthemeId
For theme app extensions, activation data is sourced from the store's published theme only.
For theme app extensions, activation data is sourced from the store's published theme only.
Anchor to Use casesUse cases
- Extension discovery: Discover installed extensions and check which extension targets are activated.
- Activation status: Determine whether theme app extension blocks and embeds are active on specific templates.
- Extension filtering: Filter extensions by type to separate UI extensions from theme app extensions.
- Feature gating: Conditionally show features based on whether required extensions are installed and activated.
Anchor to MethodsMethods
The app API is available on the shopify global object. The extensions method is asynchronous and returns a Promise that resolves to an array of objects.
- Anchor to extensionsextensionsextensions() => Promise<ExtensionInfo<ExtensionType>[]>() => Promise<ExtensionInfo<ExtensionType>[]>requiredrequired
The list of extensions from the current app.
ExtensionInfo
The `app.extensions()` method asynchronously retrieves detailed information about the app's extensions, including which targets they are activated on. It returns a Promise that resolves to an array of `ExtensionInfo` objects. Each object contains: - `handle`: The unique identifier for the extension - `type`: Either `'ui_extension'` or `'theme_app_extension'` - `activations`: Activation records (shape varies by extension type) **UI Extensions** have activations with a `target` field indicating the admin, checkout, customer account or point of sale target. **Theme App Extensions** have activations representing individual blocks/embeds, each with: - `handle`: Block/embed filename - `name`: Display name from block schema - `target`: Location type (`'section'`, `'head'`, `'body'`, or `'compliance_head'`) - `status`: Availability status (`'active'`, `'available'`, or `'unavailable'`) - `activations`: Array of theme-specific placements with `target` and `themeId` > Note: For Theme App Extensions, activation data is sourced from the store's published theme only. The array may be empty if the app has no extensions.
- activations
List of activation records for the extension. The shape depends on the extension type: - UI extensions have activations with only `target` - Theme app extensions have nested activations representing blocks/embeds
Type extends "ui_extension" ? UiExtensionActivation[] : Type extends "theme_app_extension" ? ThemeExtensionActivation[] : never - handle
The unique identifier for the extension.
string - type
The type of the extension.
Type
UiExtensionActivation
Represents an activation record for a UI extension (checkout, customer account).
- target
The target identifier for the extension activation. For example, `purchase.thank-you.block.render`.
string
ThemeExtensionActivation
Represents an activation record for a theme app block or embed. Each block/embed within a theme app extension has its own handle, status, and activations.
- activations
List of theme-specific activations for this block/embed. Contains where the block is actually placed within themes.
ThemeAppBlockActivation[] - handle
The filename of the block/embed within the theme app extension (without extension). This is configured by the developer when creating the block file.
string - name
The developer-configured display name of this block/embed, defined in the block's schema.
string - status
The availability status of this block/embed.
ActivationStatus - target
The target location type for this block/embed. - `section` for blocks - `head`, `body`, or `compliance_head` for embeds
ThemeAppBlockTarget | ThemeAppEmbedTarget
ThemeAppBlockActivation
Represents a theme-specific activation for a block/embed. Contains the specific placement within a theme.
- target
The target identifier for the block/embed placement within the theme. For example, `template--product.alternate/main/my_app_product_rating_GPzUYy`.
string - themeId
The theme ID where this block/embed is activated. Format: `gid://shopify/OnlineStoreTheme/{id}`
string
ActivationStatus
The availability status of a theme app block or embed. - `active`: Block/embed is currently present in a theme. - `available`: Block/embed exists but is not currently active. - `unavailable`: Block/embed exists but is disabled (e.g., via available_if condition). Note that if a block is present in a theme but is not available, its status will be `unavailable`.
'active' | 'available' | 'unavailable'ThemeAppBlockTarget
Target location for theme app blocks.
'section'ThemeAppEmbedTarget
Target location for theme app embeds.
'head' | 'body' | 'compliance_head'ExtensionType
The type of extension. - `ui_extension` for checkout and customer account extensions - `theme_app_extension` for theme app extensions (blocks and embeds)
'ui_extension' | 'theme_app_extension'