API versions and changes

What we add without a new version

• New endpoints, GraphQL fields and mutations.
• New fields in an answer or a webhook payload.
• New optional inputs, with a default that keeps today's behaviour.
• New webhook events. An endpoint only ever receives the events it subscribed to, so a new event reaches you only when you tick it.
• New values in a list of choices, such as a new cart mode or a new lead status.

Your integration keeps working through all of these if it ignores fields it does not know and handles a value it has not seen (log it, then carry on).

What needs a new version

Removing or renaming a field, an endpoint or an input; changing what a field means or the type it holds; making an optional input required; or tightening what a request accepts so that one that works today would fail. A change like this is made only in a new version at a new address (the REST paths gain the version, as in /api/public/v2/…), and the version you use keeps answering while you move. The account owners of every key that still calls an old version are emailed before it is switched off.

Where each version lives

• REST: /api/public/… is version 1. The OpenAPI document at /api/public/openapi.json describes it, including every webhook payload.
• GraphQL: one endpoint, /api/graphql. A field we mean to retire is marked deprecated, with what to use instead, for the whole time it still works.
• Scopes: a scope that is renamed keeps accepting the old name, so an existing key never loses access because of a rename.
• Webhooks: payloads grow by adding keys. The envelope, event, createdAt and data, and the signature recipe stay as they are.
• The ring builder script: ring-builder.js keeps every callback and option it has had. New arguments are added at the end, so a callback written for fewer arguments still works. RMJRingBuilder.version tells you which script a page has.

Related

• How an integration fits together
• Webhooks: events, payloads and signatures
• The ring builder's JavaScript SDK