Deprecation policy

We announce deprecations at least three months before deploying any breaking changes. When we deprecate a field, we record the deprecation and its intended replacement in the relevant Headless API changelog or Admin API changelog. We mark deprecated fields in our OpenAPI and GraphQL schemas, wherever the field appears. If we detect that you’re using a feature when it becomes deprecated, we notify you in-app.

What we consider a breaking change

A breaking change makes a previously supported request fail or changes a documented response or behavior in a way that requires you to update your integration. A change can be breaking even when the schema stays the same.

GraphQL (Headless API)

Change	Examples
Removing or renaming schema elements	Removing a query, mutation, field, argument, input field, or type used by existing operations. Renaming `location` to `venue` becomes breaking when `location` stops working.
Requiring previously optional input	Adding a required argument or input field, rejecting `null` where it was accepted, or removing a default so callers must supply a value they could previously omit.
Changing types or result shapes	Changing a field or argument from `Int` to `String`, returning a single object instead of a list, or replacing an object with a scalar.
Allowing previously non-null results to be null	Changing an output field from `String!` to `String`, or list items from non-null to nullable. Clients can no longer rely on receiving a value.
Changing type relationships or identity	Removing a possible type from a union, removing an interface from an object, or changing a concrete type’s name so existing fragments or `__typename` checks stop working.
Changing existing enum values	Removing or renaming an accepted enum value, or changing what an existing value means.

REST (Admin API)

Change	Examples
Removing or changing endpoints	Removing a supported API version, changing an endpoint’s URL, or requiring a different HTTP method for the same operation.
Removing, renaming, or moving request inputs	Renaming a query parameter or JSON property, or requiring a value in the request body that was previously accepted in the query string.
Requiring previously optional input	Adding a required parameter, header, or body property, or rejecting an omitted or `null` value that was previously accepted.
Changing response structure or types	Removing or renaming a response property, moving `items` into a different response envelope, returning an ID as a string instead of a number, or omitting or returning `null` for a property previously guaranteed to contain a value.
Changing the HTTP response contract	Replacing a documented `200` response containing JSON with `204` and no body, changing the content type, or removing a response header that clients need.
Changing existing enum values	Removing or renaming a supported request value, or changing the meaning of a documented response value.

Changes that affect either API

Requiring new authentication methods, permissions, or OAuth scopes for requests that existing credentials were documented to support.
Tightening validation or reducing documented request, rate, or query-complexity limits so previously supported requests are rejected.
Changing pagination parameters, response fields, or continuation behavior so an existing pagination loop no longer retrieves the results it should.
Changing documented defaults, filtering, sorting, value formats, units, or operation side effects. For example, interpreting a duration in seconds instead of milliseconds changes the meaning of the same request.
Changing documented error codes, error response structure, or retry behavior so existing error handling no longer works as documented.

Additions and compatibility

New endpoints, GraphQL fields, optional inputs, and REST response properties are compatible additions when existing requests, responses, and documented behavior remain supported. Introducing a replacement while keeping the old field working is also compatible; removing the old field is the breaking change. Adding a value to an enum used only as input does not invalidate existing requests. Adding response enum values or possible GraphQL union or interface result types requires more care: we consider those additions breaking when they expand a documented fixed set. If the API explicitly documents a set as extensible, clients need to handle additional values.

Overview

Queries

Mutations

Types

What we consider a breaking change

GraphQL (Headless API)

REST (Admin API)

Changes that affect either API

Additions and compatibility

​What we consider a breaking change

​GraphQL (Headless API)

​REST (Admin API)

​Changes that affect either API

​Additions and compatibility

What we consider a breaking change

GraphQL (Headless API)

REST (Admin API)

Changes that affect either API

Additions and compatibility