> ## Documentation Index
> Fetch the complete documentation index at: https://imprint-b3c5d5af-partner-docs-latest.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API versioning
> Choose which version of the API your integration uses, and upgrade when you're ready
Imprint releases changes that could break an existing integration under a new **API version**, named for its release date (for example, `2025-05-05`). Your integration keeps the behavior of the version it's on until you choose to upgrade. Imprint never moves you to a new version automatically.
## Changes that aren't versioned
Changes that can't break an existing integration ship to every version as soon as they're released, without a new version:
* New endpoints
* New optional request fields and query parameters
* New fields in responses and webhook payloads
Build your integration to ignore fields it doesn't recognize, so these additions never affect it.
## Changes that are versioned
Changes that could break an integration always ship in a new version. These include:
* Removing or renaming a field
* Changing a field's type or format
* Changing a status code or error type
* Adding a new value to an enum in a response or webhook payload, such as a new status on a webhook event
* Adding new validation to a request
For example, if a new application status is added to application webhooks, only integrations on the version that introduces it receive the new status. Integrations on earlier versions keep receiving only the statuses they already handle.
## How the version for a request is chosen
For every request, the API uses:
1. The version in the `x-imprint-version` request header, if you send one.
2. Otherwise, the version saved for your account in the Imprint Dashboard.
Once a request has a version, its response includes an `x-imprint-version` header with that version, so you can confirm which behavior you received. This includes error responses from the endpoint itself.
```http theme={null}
HTTP/1.1 200 OK
x-imprint-version: 2025-05-05
```
Responses to requests rejected before a version is chosen don't include the header. That covers authentication errors and requests with an unsupported `x-imprint-version` value.
## Set your version in the Imprint Dashboard
Your saved version applies to every request from your account that doesn't send the `x-imprint-version` header.
In the Imprint Dashboard, choose the environment (sandbox or production), then go to **Developers → API version**. The page shows your saved version and the version your requests are served.
Select the version you want. Production lists released versions only. Sandbox also lists `latest`, which contains changes that haven't been released yet (see [Test upcoming changes in sandbox](#test-upcoming-changes-in-sandbox)).
The new version applies to your next request. To roll back, select your previous version and save again.
Any user on your account can view the API version, but only users with the **Admin** role can change it. Sandbox and production are set separately, so changing one doesn't affect the other.
## Send a version on a request
To use a different version for a single request without changing your saved version, send the `x-imprint-version` header:
```bash theme={null}
curl https://dev.sbx.imprint.co/v2/customers/{customer_id}/link \
-u YOUR_API_KEY: \
-H "x-imprint-version: 2025-05-05" \
-H "Content-Type: application/json" \
-d '{"partner_customer_id": "member-123"}'
```
The header overrides your saved version for that request only. This is the safest way to test an upgrade: send the new version on a few requests, check the results, then change your saved version in the Imprint Dashboard.
The header name isn't case-sensitive, but the value must be exactly a released version, such as `2025-05-05`, or `latest` in sandbox.
### Unsupported versions
A request with a version that isn't supported fails with `400`, and the message lists the versions you can use. Because no version was chosen, this response doesn't include an `x-imprint-version` header.
```json theme={null}
{
"error": {
"type": "BAD_REQUEST_ERROR",
"message": "unsupported x-imprint-version \"2020-01-01\"; supported versions: 2025-05-05, 2026-10-13"
}
}
```
## Test upcoming changes in sandbox
Changes that haven't been released yet are available in **sandbox only**, under the version `latest`. To try them, either:
* send `x-imprint-version: latest` on individual sandbox requests, or
* select `latest` as your sandbox version in the Imprint Dashboard.
Upcoming changes are documented in the [unreleased docs preview](https://imprint-b3c5d5af-partner-docs-latest.mintlify.site): pick **latest** in its version selector to see the upcoming API reference, and open its changelog for the list of upcoming changes.
## Upgrade to a new version
The [changelog](/changelog) lists every version and its breaking changes. Read each entry newer than your current version. You can subscribe to it as an RSS feed to hear about new versions.
Send `x-imprint-version` with the new version on your sandbox requests, and update your integration for any changes.
Select the new version as your sandbox version in the Imprint Dashboard, and run your sandbox tests without the header.
Select the new version as your production version. If anything goes wrong, switch back to your previous version.
## Versions in the API reference
The API reference has a version selector at the top of the sidebar. Each released version has its own reference, so you can read exactly the behavior of the version your integration uses.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.