Shopify API deprecation practices

Part of a Shopify API can be deprecated if it becomes unnecessary, unsafe, or outdated. It's marked as deprecated when it's removed in a newer version of the API. The deprecation is then retroactively applied to previous stable versions of the API. When a deprecation is introduced, any further details and any relevant migration information is announced in the developer changelog.

Because each version is supported for a minimum of a year, there are always at least 9 months of overlap between versions for you to update your app to support deprecations.

GraphQL API deprecation practices

When Shopify deprecates a field in a GraphQL API, the change is communicated in one or more of the following ways:

  • A deprecation warning for the field is shown in API client tools, such as Shopify's GraphQL Explorer:

    A warning on a deprecated field in GraphiQL.

  • A notice about the deprecation is posted in the the developer changelog.

  • The API reference is updated to identify the deprecated fields and applicable alternatives.

  • If there is an imminent backwards-incompatible change that affects your app, then the emergency developer contact for your app might be contacted about the deprecation.

REST API deprecation practices

When Shopify deprecates a resource or a property of a resource in the REST Admin API, the change is communicated in one or more of the following ways:

  • Calls that include the deprecated behaviour return the response header X-Shopify-API-Deprecated-Reason and a link to get more information:

    ...
    X-Shopify-Shop-Api-Call-Limit → 1/40
    X-Shopify-API-Version → 2019-07
    X-Shopify-API-Deprecated-Reason → https://help.shopify.com/api/versioning/migration-guides/2019-07#foobar-endpoint-is-removed
    ...
  • A notice about the deprecation is posted in the developer changelog.

  • The REST Admin API reference is updated to identify the affected resource and any action you need to take.

  • If there is an imminent backwards-incompatible change that affects your app, then the emergency developer contact for your app might be contacted about the deprecation.

Sign up for a Partner account to get started.

Sign up