Versioning and deprecations

Versions #

The API is on major version v1, which is part of the path (/v1/gateway/...). Within v1 only backward-compatible changes are made.
The SDKs follow SemVer aligned with the API: the SDK’s major version is the API’s major version (1.x talks to v1). They’re all currently on 1.1.0 (changelog).

Backward-compatible changes (may ship without notice) #

New operations, modules and webhook events.
New fields in responses and in the webhook resource (the event’s version doesn’t change).
New optional parameters.
New values in response enumerations (statuses, categories).

Write your integration to tolerate them: ignore fields you don’t recognize, don’t validate the event catalog against a closed list, and treat unknown statuses as “pending review”.

Breaking changes #

Removing or renaming fields or operations, making a parameter required, or changing a type requires a new major version (/v2) or, within v1, a deprecation process with a retirement date.

How you find out about a deprecation #

A deprecated operation keeps working, but responds with RFC 8594 headers:

HTTP
Deprecation: true
Sunset: Sat, 31 Oct 2027 23:59:59 GMT
Link: </v1/gateway/...>; rel="successor-version"

All five SDKs detect those headers and log a single warning per operation (not one per call), so you see it in your logs before the retirement date:

SDK	Where the warning appears
Python	`compense_gateway` logger (`WARNING` level)
JavaScript / TS	`logger.warn` (defaults to `console`)
PHP	The PSR-3 logger you pass in `logger:`; otherwise, a silenced `E_USER_DEPRECATED` (Laravel and Symfony route it to their deprecations channel)
.NET	`ILogger`, category `Compense.Sdk`
Go	`WithLogger` (defaults to `slog.Default()`)

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("compense_gateway").setLevel(logging.WARNING)   # warnings arrive here

const client = new CompenseClient({
  apiKey: process.env.COMPENSE_API_KEY!,
  logger: { warn: (msg: string) => myLogger.warn({ source: "compense" }, msg) },
});

$client = new CompenseClient(apiKey: getenv('COMPENSE_API_KEY'), logger: $psr3Logger);

builder.Logging.AddFilter("Compense.Sdk", LogLevel.Warning);
builder.Services.AddCompense(builder.Configuration.GetSection("Compense"));

client, err := compense.NewClient(os.Getenv("COMPENSE_API_KEY"),
	compense.WithLogger(slog.New(slog.NewJSONHandler(os.Stderr, nil))))

curl -sI "https://sandbox.dev.compense.co/gw/v1/gateway/health/" -H "X-API-Key: $COMPENSE_API_KEY" \
  | grep -iE '^(deprecation|sunset|link):'

Alert on the warnings

Create an alert in your logging platform for Compense deprecation warnings: it’s the cheapest way to avoid finding out about a retirement on the day it happens.

Current deprecations #

What	Since	Replacement
Paths without a version prefix, `/gateway/...`	v1	`/v1/gateway/...` (the SDKs already use the new ones)
Python SDK 1.0: `fx.quote/convert(from_currency=, to_currency=)`	1.1.0	`sell_currency=`, `buy_currency=`
Python SDK 1.0: `test_clocks.create(name=)`, `test_clocks.advance(by_seconds=)`	1.1.0	`create(frozen_time=)`, `advance(delta_seconds=)`
Python SDK 1.0: `sandbox.trigger_webhook`	1.1.0	`webhooks.endpoints.send_test`
Python SDK 1.0: `sandbox.simulate.wallet_transfer_advance` / `credit_disburse_advance`	1.1.0	`simulate.wallet_transfer` / `simulate.credit_disbursement`

The old Python SDK names keep working with a DeprecationWarning until 2.0.

The JavaScript, PHP, .NET and Go SDKs started at 1.1.0 and only include the contract names.