Skip to content
Cuvo IntegrationsDocumentationPortal

Versioning

What we may change without telling you, what we may not, and how long a deprecation runs.

The version is in the path. Every operation lives under /v1, and /v1 is a promise about shape, not a release train.

What can change without notice

These are additive, and your client must tolerate them:

  • New endpoints.
  • New optional request fields. Anything required today stays required, and nothing new becomes required.
  • New response fields. Parse leniently. Ignore what you do not recognise rather than failing on it.
  • New enum values. New case statuses, order statuses, order block reasons, event types, problem codes and billing kinds all arrive this way. Handle an unknown value by falling through to a default rather than throwing. This is why kind on a billing charge is a string rather than an enum.
  • New event types. A webhook endpoint only receives the types it subscribed to, so a new type reaches you when you ask for it.
  • Reworded detail and title on a problem. Switch on code, never on the prose.

What will not change inside v1

  • A field is never removed or renamed.
  • A field never changes type, and an optional field never becomes required.
  • An endpoint is never removed and its path never changes.
  • The meaning of an existing enum value never changes.
  • The code on a problem never changes what it means.
  • An identifier prefix never changes. A case_… is always a case.

Event payload versions

Event types carry their own version, case.approved.v1. A payload change ships as a new type rather than a silent break, so case.approved.v2 would arrive beside v1 and you would subscribe to it when you were ready. That is why the suffix exists on every type even though none has needed a second version yet.

Breaking changes

A breaking change only ever ships under a new path version. /v1 keeps behaving as /v1.

When an operation or a field is deprecated:

  1. It is announced in the changelog with a date and a replacement.
  2. Responses carry a Deprecation header naming the date it stops working.
  3. It keeps working for twelve months from the announcement.

Twelve months is a floor, not a target. Nothing in /v1 is deprecated today.

Pinning

The contract this API validates against is published as an OpenAPI 3.1 document at /docs/openapi.yaml. It is generated from the same schemas the server uses, and a build fails if the two drift, so the document is not a description of the API written alongside it. It is the API.

Both SDKs generate their types from that document, so upgrading an SDK is how you pick up an additive change, and neither can compile against a shape the server does not serve. See SDKs.

Status and incidents

Current service state is on the status page.