Versioning

​

Where we are

The Offergrid API is at version 1. There is no version segment in the URL and no version header — https://api.offergrid.io/provider/offers is the current and only address for that endpoint. We evolve version 1 additively rather than shipping v2, v3, v4 URLs. That keeps integrations working without a migration project every time the product grows.

​

What will not change without notice

Within version 1, we treat these as a contract:

• Endpoint paths and methods. An existing path will not be removed, renamed, or change its HTTP method.
• Existing response fields. A field that exists will not be removed, renamed, or change type.
• Existing request fields. A currently-optional field will not become required, and accepted values will not be narrowed.
• Status codes for existing conditions. A request that returns 409 today will not start returning 400.
• Enum values you already receive. An existing order status or offer category will not be renamed out from under you.
• The webhook envelope. { id, type, version, data } is stable. An incompatible change to an existing event type’s payload bumps version.

​

What can change at any time

These are routine, and your integration must tolerate them:

• New fields in responses. Parse permissively and ignore fields you do not recognize. A parser that rejects unknown fields will break on a normal release.
• New optional request fields.
• New endpoints, new query parameters, and new webhook event types. A webhook only receives the types it subscribes to, so a new type will not arrive unannounced — but a switch on type should still have a default branch.
• New enum values. Handle an unrecognized status by falling through rather than throwing.
• Ordering of array results, unless an endpoint documents a sort.
• Error message wording. Branch on the HTTP status code, never on the message string.

​

Deprecation

If we ever need to make a breaking change, this is the process:

1. Announce in the changelog with the reason, the replacement, and a removal date.
2. Ship the replacement first, so both old and new work at the same time.
3. Notify integrators directly — we know which teams call which endpoints, and we will email you rather than expect you to be watching a page.
4. Leave at least 90 days between the announcement and removal.

Nothing is deprecated today.

​

Preview features

Some capabilities ship to specific partners before they are general. If something is not documented here, treat it as unsupported and subject to change regardless of whether it appears to work — including undocumented fields you may see in a response.

​

Staying informed

• The changelog records every API-affecting change.
• The OpenAPI specs are regenerated from the API on every change and published at stable URLs — provider, reseller, public. Diffing them in CI is the most reliable way to detect a change that affects you.
• For anything that would materially affect your integration, email support@offergrid.io and we will make sure you are on the notification list.

​

Next steps