---
title: App API
description: >-
  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.
api_version: v1.0
source_url:
  html: >-
    https://shopify.dev/docs/api/app-home/latest/apis/authentication-and-data/app-api
  md: >-
    https://shopify.dev/docs/api/app-home/latest/apis/authentication-and-data/app-api.md
api_name: app-home
---

# App API

**Info:**

App Bridge isn't versioned with Polaris. App Bridge APIs and web components are identical in every App Home reference version.

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 extension
* `type`: 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 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](https://shopify.dev/docs/apps/build/online-store/theme-app-extensions), activation data is sourced from the store's published theme only.

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

### Methods

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 `ExtensionInfo` objects.

* **extensions**

  **() => Promise\<ExtensionInfo\<ExtensionType>\[]>**

  **required**

  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. For UI Extensions targeting checkout, activation data is sourced from the store's published checkout profile 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

  ```ts
  Type extends "ui_extension" ? UiExtensionActivation[] : Type extends "theme_app_extension" ? ThemeExtensionActivation[] : never
  ```

* handle

  The unique identifier for the extension.

  ```ts
  string
  ```

* type

  The type of the extension.

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

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

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

  ```ts
  string
  ```

* name

  The developer-configured display name of this block/embed, defined in the block's schema.

  ```ts
  string
  ```

* status

  The availability status of this block/embed.

  ```ts
  ActivationStatus
  ```

* target

  The target location type for this block/embed. - \`section\` for blocks - \`head\`, \`body\`, or \`compliance\_head\` for embeds

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

  ```ts
  string
  ```

* themeId

  The theme ID where this block/embed is activated. Format: \`gid://shopify/OnlineStoreTheme/{id}\`

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

```ts
'active' | 'available' | 'unavailable'
```

### ThemeAppBlockTarget

Target location for theme app blocks.

```ts
'section'
```

### ThemeAppEmbedTarget

Target location for theme app embeds.

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

```ts
'ui_extension' | 'theme_app_extension'
```

Examples

### Examples

* ####

  ##### Description

  Retrieve extension information. This example fetches all installed extensions, returning an array with UI and theme app extension data.

  ##### js

  ```js
  const extensions = await shopify.app.extensions();

  // Example response:
  // [
  //   // UI extension
  //   {
  //     handle: 'checkout-extension-1',
  //     type: 'ui_extension',
  //     activations: [
  //       {target: 'purchase.thank-you.block.render'},
  //       {target: 'customer-account.order-status.block.render'},
  //     ],
  //   },
  //   // Theme app extension with nested blocks/embeds
  //   {
  //     handle: 'my-theme-app-extension',
  //     type: 'theme_app_extension',
  //     activations: [
  //       {
  //         target: 'section',
  //         handle: 'product-rating',
  //         name: 'Product Rating',
  //         status: 'active',
  //         activations: [
  //           {
  //             target: 'template--product.custom/main/my_app_product_rating_GPzUYy',
  //             themeId: 'gid://shopify/OnlineStoreTheme/123',
  //           },
  //         ],
  //       },
  //       {
  //         target: 'head',
  //         handle: 'analytics-widget',
  //         name: 'Analytics Widget',
  //         status: 'active',
  //         activations: [
  //           {target: 'theme', themeId: 'gid://shopify/OnlineStoreTheme/123'},
  //         ],
  //       },
  //     ],
  //   },
  // ];
  ```

* ####

  ##### Description

  Filter extensions by type. This example separates UI extensions from theme app extensions, which have different activation structures. Useful for checking admin targets vs storefront placements.

  ##### js

  ```js
  const extensions = await shopify.app.extensions();

  // Get only UI extensions
  const uiExtensions = extensions.filter(ext => ext.type === 'ui_extension');

  // Get only theme app extensions
  const themeExtensions = extensions.filter(ext => ext.type === 'theme_app_extension');
  ```

***