Versioning and deprecation policy

What version means here

The v1 in /public/v1 and /partner/v1 is the major version. Within a major version, changes are additive: new fields, new endpoints, new optional parameters. Your integration should ignore unknown JSON fields it does not use, so an additive change never breaks you. A change that would break existing clients — removing a field, renaming one, tightening a type — waits for a new major version rather than shipping into v1.

How deprecations are signalled

When something is scheduled for removal it is announced on the developer changelog ahead of time, with a deprecation window during which both old and new behaviour work. Where practical, deprecated responses also carry a signal (for example a Deprecation or Sunset header) so you can detect reliance programmatically. Watch the changelog and treat any deprecation notice as a dated task.

Keeping an integration stable

Three habits keep you resilient: tolerate unknown fields, branch on machine error codes rather than message text, and pin the version you built against by using the explicit /v1 path. Do not screen-scrape the marketing site for figures the API already publishes — read config/pricing and products, which stay contract-stable within the version.

Frequently asked questions

Will a new field ever break my integration?

Not if you ignore unknown fields. Additive changes — new fields and endpoints — ship within v1, so a client that reads only the fields it needs is unaffected. Breaking changes wait for a new major version.

How much notice do I get before a breaking change?

Breaking changes are announced on the changelog ahead of a deprecation window during which both behaviours work. Subscribe to the changelog and act on any deprecation notice before the sunset date.