Skip to main content

​
Overview

The API uses date-based versioning to manage breaking changes. Each version is identified by a date string in YYYY-MM-DD format (e.g., 2026-03-09). When we introduce a breaking change, we release it under a new version date while keeping older versions fully functional.

​
How versioning works

Every merchant account has a default API version assigned at the time of account creation. All requests from that account use the default version unless overridden. You can check your current default version in the dashboard under Settings > API Version.

​
Setting the version per request

Use the X-API-Version header to override your account’s default version on any individual request: 
curl https://api.leanrails.com/v1/payment_intents \
  -u "$API_KEY:" \
  -H "X-API-Version: 2026-03-09"
The response includes a header confirming the version that was used: 
X-API-Version: 2026-03-09

​
Version precedence

SourcePriority
X-API-Version header on the requestHighest (always wins)
Account default versionUsed when no header is provided

​
What constitutes a breaking change

The following changes require a new API version:
  • Removing or renaming a field in a response body
  • Changing the type of an existing response field
  • Changing the default value of a request parameter
  • Adding a new required request parameter
  • Changing error response codes for existing scenarios
  • Changing the behavior of an existing endpoint
The following changes are non-breaking and can be added to any version:
  • Adding a new optional request parameter
  • Adding a new field to a response body
  • Adding a new endpoint
  • Adding a new error code for a new scenario
  • Adding a new value to an existing enum (for response fields)

​
Upgrading your version

To upgrade your account’s default version:
  1. Review the changelog for all changes between your current version and the target version.
  2. Test your integration against the new version using the X-API-Version header.
  3. Update your default version in the dashboard under Settings > API Version.
# Test a specific version before upgrading your default
curl https://api.leanrails.com/v1/payment_intents \
  -u "$API_KEY:" \
  -H "X-API-Version: 2026-03-09"
Upgrading your default API version affects all requests that do not include an explicit X-API-Version header. Test thoroughly before upgrading.

​
Pinning a version in code

For production stability, pin the version in your API client configuration: 
const fetch = require("node-fetch");

const API_KEY = process.env.API_KEY;
const API_VERSION = "2026-03-09";
const credentials = Buffer.from(`${API_KEY}:`).toString("base64");

async function apiRequest(path, options = {}) {
  const response = await fetch(`https://api.leanrails.com${path}`, {
    ...options,
    headers: {
      Authorization: `Basic ${credentials}`,
      "X-API-Version": API_VERSION,
      ...options.headers,
    },
  });

  return response.json();
}

// All requests now use the pinned version
const intents = await apiRequest("/v1/payment_intents");

​
Version history

VersionDateSummary
2026-03-09March 9, 2026Current version. Initial public release.
New versions are announced in the changelog and via email to account owners at least 30 days before they become the default for new accounts.