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 the 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 GraphQL Admin 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 resource or property return the response header X-Shopify-API-Deprecated-Reason.
  • 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