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 (24)

Supported targets

Anchor to PropertiesProperties

The shopify global object provides the API version for customer account extensions. Access the following properties on shopify to determine which version your extension is running against.

Anchor to version version required: The API version your extension is running against. Use this to conditionally enable features or handle breaking changes when your extension supports multiple API versions.

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

export default async () => {

render(<Extension />, document.body);

};

function Extension() {

const version = shopify.version;

return (

<s-text>

Running on API version: {version}

</s-text>

);

}

Examples

Description

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

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const version = shopify.version;

  return (
    <s-text>
      Running on API version: {version}
    </s-text>
  );
}

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.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default async () => {
  render(<Extension />, document.body);
};

function Extension() {
  const version = shopify.version;
  const supportsNewFeature =
    version >= '2026-04';

  return (
    <s-stack direction="block" gap="base">
      {supportsNewFeature ? (
        <s-banner heading="New feature available">
          This extension is using the latest API
          features.
        </s-banner>
      ) : (
        <s-banner heading="Update available">
          Upgrade your API version to access new
          features.
        </s-banner>
      )}
    </s-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?