> ## Documentation Index
> Fetch the complete documentation index at: https://offergrid.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How the Offergrid API changes, what we promise not to break, and how deprecations work

## 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.

<Warning>
  The single most common cause of a broken integration is a client that
  validates responses strictly. Be liberal in what you accept.
</Warning>

## Deprecation

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

1. **Announce** in the [changelog](/docs/api-reference/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](/docs/api-reference/changelog) records every API-affecting change.
* The OpenAPI specs are regenerated from the API on every change and published
  at stable URLs — [provider](/docs/openapi/openapi-provider.json),
  [reseller](/docs/openapi/openapi-reseller.json),
  [public](/docs/openapi/openapi-public.json). 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](mailto:support@offergrid.io) and we will make sure
  you are on the notification list.

## Next steps

<CardGroup cols={2}>
  <Card title="Changelog" icon="clock-rotate-left" href="/docs/api-reference/changelog">
    Dated record of API changes
  </Card>

  <Card title="API conventions" icon="list-check" href="/docs/api-reference/conventions">
    List responses, identifiers, timestamps, and money
  </Card>
</CardGroup>