API Versioning

The Lithic API is versioned with dated releases in YYYY-MM-DD format. A version fixes the request and response shape of every endpoint at a point in time. A breaking change ships in a new version so that you are able to update your integration.

Most changes we make are backwards compatible and reach every version. New versions are created when Lithic needs to make breaking changes to our API contract.

Backwards compatibility

The Lithic API will not make backwards-incompatible changes (such as removing a parameter from the API) without reaching out to you first. We're continually making backwards-compatible changes to the API, however. A record of backwards-compatible changes can be found in our Changelog. Examples of backwards-compatible changes which we do not consider "breaking" include:

1. Adding new optional request parameters to existing API methods.
2. Adding new properties to existing API responses.
3. Adding new API resources or methods.
4. Adding new values to existing enums.
5. Adding new webhook event types.
6. Changing the order of properties in existing API responses.
7. Changing the length or format of opaque strings, such as resource IDs, error messages, and other human-readable strings.

📘

We recommend handling unknown values gracefully, so additive changes don't interrupt your integration:

• Enum values: For new enum values. You should handle values your code doesn't recognize rather than rejecting the response, and add support for them as your integration needs. If you use strict enum types, add a case to catch these such as UNKNOWN.
• Webhook event types: If you subscribe to all events, new event types are delivered automatically. Return a 200 for event types you don't handle. You may ignore or store unknown events. A non-200 response causes the event to be retried.

Initial versioning

Since establishing API versioning, clients who do not pass a version header, will interact with our 2024-01-15 version. This is our initial first version. This behavior will end when 2024-01-15 retires.

Available versions

Specifying a version

Send the api-version request header with the version you want:

curl --request GET \
     --url 'https://api.lithic.com/v1/cards' \
     --header 'Accept: application/json' \
     --header 'Authorization: YOUR_API_KEY' \
     --header 'api-version: 2026-07-01'

The header is per request. This makes it possible to send different versions per request if needed.

Unrecognized versions

A request that sends api-version with a value we do not recognize is rejected with a 400. That covers a malformed date, a version we have never published, and one that is not available to you. The request is not served against a different version in its place.

Omitting the header is not an error. Those requests are served against 2024-01-15, as described above.

Because an invalid value fails on the first request rather than quietly resolving to something else, a typo surfaces while you are integrating instead of as a behavior difference later.

Deprecation notices

When a version is scheduled for retirement, responses to requests on that version carry the X-LITHIC-API-VERSION-DEPRECATION response header naming the version and the date after which it will no longer be supported. No version currently carries a deprecation date.

We will contact you before retiring a version you are using. Log this header in your integration so you learn about a retirement from your own traffic as well.

Matching the docs to your version

The version selector at the top of this site switches both the API reference and these guides together. Select the version you send in the api-version header, and the parameters, response shapes, and behavior described throughout the docs are the ones your requests will get.

The selector in our docs labels versions with a v prefix, v2026-07-01, which is not used in the API header value.

SDKs

Each Lithic API library is built against a single API version. The release you install determines the API version your requests use. Check the SDK release notes, SDK documentation and our changelog to know which API version the SDK is using. To move to a newer API version, upgrade to the library release built for it.

Choosing a version

If you call the API directly, send an explicit api-version on every request rather than relying on defaulting.

To move to a newer version, test it in Sandbox first, then roll the header out in Production. If you have questions about a specific version, contact support.lithic.com or your Lithic representative.