---
title: Version API
description: >-
  The Version API lets you read the current API version your extension is
  running on. Use this API to implement version-specific logic, log the active
  version for debugging, or conditionally enable features that depend on a
  specific API version.
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/version-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/platform-apis/version-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.

# Version API

The Version API lets you read the current API version your extension is running on. Use this API to implement version-specific logic, log the active version for debugging, or conditionally enable features that depend on a specific API version.

### Use cases

* **Apply version-specific behavior**: Check the API version at runtime to enable or disable features that are only available in certain versions.
* **Log the active version for debugging**: Include the API version in logs or error reports to help diagnose issues across different environments.
* **Display version information**: Show the current API version in a diagnostic or admin-facing view to help with troubleshooting.

### 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 Version API object provides the API version for customer account extensions. Access the following properties on the API object to determine which version your extension is running against.

* **version**

  **Version**

  **required**

  The API version your extension is running against. This is the version specified in your [`shopify.extension.toml`](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#configuration) file.

### Version

The API version string for the extension. Corresponds to the version specified in the extension’s \[\`shopify.extension.toml\`]\(/docs/api/customer-account-ui-extensions/2025-07#configuration) file.

```ts
string
```

Examples

### Examples

* #### Read the current API version

  ##### Description

  Access the API version string that your extension is running on. This example reads \`shopify.version\` and displays it in a text component.

  ##### React

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

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

  function Extension() {
    const {version} = useApi();

    return (
      <Text>
        Running on API version: {version}
      </Text>
    );
  }
  ```

  ##### TS

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

  export default extension(
    'customer-account.order-status.block.render',
    (root, {version}) => {
      const text = root.createComponent(
        Text,
        {},
        `Running on API version: ${version}`,
      );

      root.appendChild(text);
    },
  );
  ```

* #### Apply version-specific logic

  ##### Description

  Conditionally render content based on the API version to handle feature availability across versions. This example compares \`shopify.version\` against a minimum version string to decide which banner to display.

  ##### React

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

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

  function Extension() {
    const {version} = useApi();
    const supportsNewFeature = version >= '2026-04';

    return (
      <BlockStack>
        {supportsNewFeature ? (
          <Banner title="New feature available">
            This extension is using the latest API
            features.
          </Banner>
        ) : (
          <Banner title="Update available">
            Upgrade your API version to access new
            features.
          </Banner>
        )}
      </BlockStack>
    );
  }
  ```

  ##### TS

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

  export default extension(
    'customer-account.order-status.block.render',
    (root, {version}) => {
      const supportsNewFeature = version >= '2026-04';

      const banner = root.createComponent(
        Banner,
        {
          title: supportsNewFeature
            ? 'New feature available'
            : 'Update available',
        },
        supportsNewFeature
          ? 'This extension is using the latest API features.'
          : 'Upgrade your API version to access new features.',
      );

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

      root.appendChild(stack);
    },
  );
  ```

***

## Best practices

* **Don't over-rely on version checks**: Prefer feature detection over version comparison when possible. Version checks can become brittle as APIs evolve.
* **Use version info for debugging**: Include `shopify.version` in error logs or diagnostic output to make it easier to reproduce and triage issues.
* **Keep version comparisons simple**: Compare version strings using straightforward logic. Version strings follow a `YYYY-MM` format that supports lexicographic comparison.

***

## Limitations

* The version string reflects the API version your extension is configured to use, not the latest available version. It won't change unless you update your extension's configuration.
* The Version API is read-only. You can't change the API version at runtime. It's determined by the `api_version` field in your `shopify.extension.toml` file.

***