Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

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.

Anchor to version version required: The API version your extension is running against. This is the version specified in your shopify.extension.toml 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.

string

Examples

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>

);

}

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

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

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

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

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

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?