> For the complete documentation index, see [llms.txt](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/atlaspay-api/schema-versioning-and-compatibility.md).

# Schema Versioning & Compatibility

Each webhook event includes an `api_version` field indicating the schema version used to generate the payload:

```json
{
  "id": "evt_98234",
  "object": "event",
  "api_version": "2026-01-01",
  "type": "payment.succeeded",
  "created": 1710509051,
  "livemode": true,
  "data": {
    "object": {
      "id": "pay_123",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  }
}

```

**How versioning works**

Webhook schema versions are pinned per endpoint. When a webhook endpoint is created, it is assigned the current schema version at that time. Existing endpoints continue receiving events in their configured version until you explicitly upgrade them. The REST API version (such as /v2) is independent of the webhook schema version and does not affect payload structure.

**Upgrading schema versions is a breaking change**

Upgrading a webhook endpoint to a new schema version should be treated as a breaking integration change. Test schema upgrades in a staging environment before applying them to production endpoints.

**Non-breaking changes (no version bump)**

AtlasPay may introduce the following changes without creating a new version identifier:

* Adding new optional fields
* Adding new nested objects
* Adding new event types
* Adding new enum values to existing fields

**Your integration must tolerate forward-compatible changes**

Strict schema validation that rejects unknown fields or unrecognized enum values will cause outages when new capabilities are introduced. Your integration must:

* Ignore unknown fields
* Avoid strict schema validation that rejects additional properties
* Handle unknown enum values gracefully (e.g. log and skip, do not throw)

**Breaking Changes (new version required)**

The following changes are only made in a new schema version:

* Removing fields
* Renaming fields
* Changing field types
* Changing required/optional status of fields

**Schema versions and event replay**

When an event is replayed, the payload is rendered using the schema version currently configured on the destination endpoint, not the version active at the time of original delivery. If you have upgraded your endpoint's schema version since the original event was delivered, replayed payloads may differ structurally from the originals.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://constanza-gobbo.gitbook.io/technical-documentation-portfolio/atlaspay-api/schema-versioning-and-compatibility.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.