# Versioning & deprecation

> The version is in the path (/v1); additive changes ship without a bump; breaking changes get /v2 with at least twelve months of overlap, Deprecation and Sunset headers and a changelog entry.

Source: https://developers.processcart.com/guides/versioning

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](https://developers.processcart.com/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](https://developers.processcart.com/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](https://developers.processcart.com/guides/field-values) — 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](https://developers.processcart.com/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.