API versions and upgrades

An API version names the request and response shapes your integration was built against. Flint keeps serving that shape after newer versions ship, so a release never changes a response you already parse. You move forward when you choose to, one merchant default, webhook endpoint, or partner app at a time, and you can undo the move for 72 hours.

Versions are dated, YYYY-MM-DD, and the URL prefix is always /v1. A new version exists only when a release contains a breaking change. Additive changes, such as new fields, endpoints, and values in open enums, ship continuously without a new version.

Two versions exist today:

• 2026-09-07, current. Balance transaction fee signs flip, the transaction timestamp becomes occurred_at, relationships use typed related_resource ids, and tax categories split into line_item_tax_category and charge_tax_category. All 19 balance transaction types and 6 statuses keep their meanings.
• 2026-02-01, supported. The baseline. Serves the earlier field names and fee signs.

The changelog lists every change in a release with the schemas and operations it touches.

Choose a version#

Send Flint-Version on any request to get that version's shape, regardless of your defaults:

curl https://api.withflintpay.com/v1/customers?page_size=10 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Flint-Version: 2026-02-01"

When the header is absent, Flint falls through this list and uses the first version it finds:

1. The Flint-Version header.
2. The partner app's version, for a request authenticated with a partner install token.
3. The merchant's default version. This covers API keys and the buyer-facing credentials the merchant issues: checkout sessions, customer sessions, portal sessions, and invoice access tokens.
4. The current version, when no merchant or partner app is involved.

One default covers live and test mode. API keys do not carry their own version. To try a newer version without touching live traffic, send its header on your test-mode requests.

An unknown or malformed version returns 400 INVALID_API_VERSION and lists the supported versions in details. A retired version returns 410 API_VERSION_RETIRED.

Check the version you received#

Every response, success or error, carries the served version in a Flint-Version header. Successful JSON responses repeat it in meta.api_version:

HTTP/1.1 200 OK
Flint-Version: 2026-02-01

{
  "data": { "...": "..." },
  "meta": {
    "request_id": "d5f2b8c6-4e7a-4c9d-8f21-6b3a9e5c7d04",
    "api_version": "2026-02-01"
  }
}

The served version can be older than the one you asked for in one case: an idempotent replay. Flint stores the response at the version of the original request and never rewrites it into a newer shape, so a replay is served at the older of the stored version and the version you request now. When a response does not match your types, read Flint-Version before you read the body.

The request log records requested_api_version, requested_api_version_source (header, partner_app, merchant, or current), and served_api_version for every request. After an upgrade, check served_api_version on recent entries to confirm nothing is still on the old shape.

SDK and CLI versions#

The Node SDK sends the version its types were generated for on every request, so it is unaffected by your merchant default. Its apiVersion option accepts only that exact version. The option exists so TypeScript can check the version your integration expects; it does not switch the SDK to another contract. To move a Node integration to a new version, install the SDK release that targets it. Run the two SDK releases side by side to migrate one call site at a time, or send Flint-Version on raw HTTP requests.

The CLI sends the version of its bundled OpenAPI specification. flint doctor reports the CLI version, the server's current version, and the changelog, and keeps requesting its bundled version. Updating the CLI can move that version independently of your merchant default.

Upgrade#

1. Read the impact report#

Open Developers > Versions. It shows your merchant default beside the current version and lists the routes your integration called in the selected environment during the last 90 days that a newer release changes. A route you have not called in that window can still be affected, so read the changelog entries for the target release as well.

2. Test against the target version#

Send Flint-Version: 2026-09-07 from a test-mode client and exercise the affected routes. Check what your code does with renamed fields, fields it no longer receives, and error responses, not only the successful path.

The API reference always describes the current version. To generate types or diff schemas for a specific version, fetch that version's specification:

curl 'https://api.withflintpay.com/v1/openapi.json?version=2026-02-01'

The specification's x-flint-api-version names the version it describes. info.version stays v1.

3. Move the merchant default#

Once test-mode traffic looks right, update the default on the Versions screen or through the API:

curl -X PATCH https://api.withflintpay.com/v1/merchants/mer_1kmn0aExample \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "api_version": "2026-09-07" }'

The merchant records the version it moved from and when the rollback window closes:

{
  "merchant_id": "mer_1kmn0aExample",
  "api_version": "2026-09-07",
  "api_version_previous": "2026-02-01",
  "api_version_changed_at": "2026-09-14T15:04:05Z",
  "api_version_rollback_expires_at": "2026-09-17T15:04:05Z"
}

Requests that send Flint-Version are unaffected by the default, including every Node SDK request. Move those by upgrading the client.

4. Move webhook endpoints and partner apps#

Webhook endpoints can follow the merchant default or pin a dated version. Partner apps keep their own api_version:

• Webhook endpoint. Set api_version to "default" to follow the endpoint owner's merchant default, or to a supported date such as "2026-02-01" to pin it. New endpoints follow the default when api_version is omitted. Existing dated pins stay pinned. Change either mode on the Versions screen or with PATCH /v1/webhook-endpoints/{webhook_endpoint_id}. Omit the field on updates to leave it unchanged; null is not accepted.
• Partner app. Covers install-token requests that omit the header, in live and test mode. Change it on the Versions screen or with PATCH /v1/developer/partner/apps/{partner_app_id}.

Upgrade webhook endpoints with the two-endpoint procedure below so a retry cannot surprise a consumer that only understands the new shape.

Roll back#

For 72 hours after a change, the Versions screen offers to restore the version you moved from, as long as that version is still supported. Rolling back a merchant changes only requests that omit Flint-Version. Rolling back a partner app changes only install-token requests that omit it. Neither overrides an explicit header.

Switching between a dated pin and "default" clears the endpoint rollback offer. You can still choose any supported date or follow the default again.

Rolling back a webhook endpoint also changes pending retries, because Flint reads the endpoint's version when it delivers. Deliveries are still capped at the event's recorded version.

After 72 hours the dashboard drops the offer, and api_version_previous clears. You can still set any supported version through the update routes above, or send it in Flint-Version on individual requests.

Upgrade webhook consumers#

An endpoint set to "default" changes when its merchant default changes, including rollbacks. An endpoint pinned to a date changes only when you update that endpoint. Every event records the version its payload was created at, and each delivery uses the older of that recorded version and the endpoint's version at delivery time. Flint never rewrites an event into a newer shape.

That has one consequence for your consumer: after you upgrade an endpoint, retries of events created before the upgrade still arrive in the old shape. Read the envelope's api_version and keep accepting the old shape until those retries drain.

Validate a new consumer on a second endpoint before you switch business processing. Upgrade with two endpoints walks through deduplicating across both handlers and keeping a rollback path.

Preview APIs and open enums#

Two kinds of change happen without a new version, and your code should expect both.

Preview APIs. An endpoint or field marked Preview in the API reference sits outside the version guarantee. It can change or be removed with 30 days notice in the changelog, even when you pin a version. Preview methods and types carry an @preview tag in the Node SDK. Every preview either becomes stable or is removed within 180 days of introduction.

Open enums. An enum marked x-flint-enum: open in the OpenAPI specification can gain values at any time. Statuses are open, because product lifecycles grow. Keep unknown strings and handle them in a default branch. An enum marked x-flint-enum: closed, such as a type discriminator or an error code, only changes in a versioned release.

Release schedule and support#

Breaking changes ship in dated releases, at most two per year. Each release appears in the changelog with the operations and schemas it changes.

A version stays supported for at least 24 months after its successor ships, and shipping a successor never retires it on its own. Retirement is announced at least 12 months ahead in the changelog, by email, and in the API: responses on a version scheduled for retirement carry Deprecation and Sunset headers. A published retirement date never moves earlier. If Flint extends one, the changelog entry states why.

Next steps#

• Webhooks: the event envelope, signature verification, and the two-endpoint upgrade procedure.
• Idempotency: why a replay is served at the original request's version.
• Debugging: the request log and how to trace a single request by its id.
• Node SDK and CLI: how each client picks its version.
• Changelog: every versioned change, with the schemas and operations it touches.