Versioning & deprecation

The API version is in the path: https://app.processcart.com/api/v1/…. v1 is the current and only version.

Non-breaking changes ship within v1

These may happen at any time and are announced in the changelog:

• new endpoints, new optional query parameters and new optional body members;
• new members in responses and in webhook payloads;
• new event types, new activity types, new error codes, new enum values (statuses, field types, formats);
• loosened validation (accepting something that was refused), new limits that are higher than today's.

A client must therefore tolerate unknown members and unknown enum values: ignore a member it does not know, and treat an unknown code, event type or status the way its HTTP status or context suggests. The OpenAPI document marks every growable enum with x-processcart-open-enum: true.

Breaking changes get a new version

Removing or renaming a member, changing a type or a canonical format, tightening validation, changing the meaning of a status code, or dropping an endpoint is a breaking change. It ships as /v2, and:

• /v1 keeps working for at least twelve months after /v2 is announced;
• the old operations send Deprecation (RFC 9745, the date the deprecation took effect) and Sunset (RFC 8594, the date they stop answering — never less than 90 days after Deprecation) headers on every response;
• the changelog carries the migration notes the day the headers appear.

Within a version, a single operation may also be deprecated the same way (headers + a changelog entry + the 90-day minimum) when a replacement exists.

Before the public launch the API is pre-release: a breaking change may ship inside /v1 with a changelog entry and no /v2 (the 2026-10-12 move from If-Match / ETag to Expected-Revision is the one such change so far). The policy above applies in full from the launch date the changelog announces.

What never changes without a version bump

• The canonical value shapes on Field values & typing — a number stays a number, a percent stays a fraction, a date stays YYYY-MM-DD.
• The envelope { data, nextCursor, hasMore }, the Problem Details shape and the code values already published.
• The Standard Webhooks headers and signature scheme.

Staying informed

The changelog lists every change with its date; it is written by hand and updated with every release, including the migration notes on the day any Deprecation / Sunset header appears. The OpenAPI document's info.version names the API version and comes straight from the code that serves the API, as does every reference page.