API stability and service levels

What Kustom may change in an API without bumping its version, how to write a client that survives those changes and the latency, availability and maintenance objectives Kustom publishes for its integration APIs.

Two promises govern how much you can lean on a Kustom API — a compatibility promise about what may change under you, and a service level objective about latency and availability. Both are about writing a client that keeps working. A client that accepts additive change and handles a slow response is a client that doesn’t need to be redeployed every time Kustom ships. Anything Kustom can’t change compatibly results in a version bump of the API.

Changes Kustom treats as non-breaking

These can land at any time, without a version bump. Your client must tolerate all of them:

A response body appearing where there previously was none.
New optional or read-only fields and properties.
Fields reordered within a JSON object.
New HTTP response headers.
New values in an enum, where the enum has a defined default.
New HTTP methods on an existing resource.

Writing a client that survives them

Accept any 2xx as success. Don’t code against one specific success status.
Treat any 4xx as a client-side error and any 5xx as a server-side one, without branching on the exact status where the class is enough.
Ignore fields you don’t recognize. Strict deserialization that throws on an unknown property turns an additive change into an outage.
Give every enum a default branch. A new enum value is non-breaking by this policy, so your code will meet one.
Never depend on field order in a JSON object, and never on the wording of an error_messages string. Only error_code is a contract.

Latency objectives

Latency is the time to respond, at the 99th percentile, measured at the edge of the region the service runs in. It excludes internet network latency, so what you observe from your own infrastructure will be higher.

API	Operation	p99
Order Management	Read operations	800 ms
Order Management	All other operations	1000 ms
Hosted Payment Page	Create a payment session	200 ms
Customer Token	Place an order on a token	5000 ms
Settlements	Read operations	6000 ms
Disputes	All operations	4000 ms
Card settlements	Create a card settlement	1000 ms

Set client timeouts well above these numbers, not at them — a p99 objective isn’t a cap. The placing-an-order-on-a-token figure is the one that catches people out: 5 seconds is normal, so a 2 second timeout on a recurring charge will manufacture failures.

Availability objectives

Availability is measured monthly, per service feature type.

Service feature type	Availability objective
Transaction critical services	99%
Transaction non-critical services	99%
Additional services	99%

It’s calculated as the number of requests answered with a 2xx, 3xx or 4xx divided by all requests in the measurement period. Note what that means in practice: a 4xx counts as available, because the service did respond correctly to a bad request. Only 5xx and non-responses count against the objective.

Periods with no traffic are excluded, as is unavailability caused by force majeure affecting all of Kustom’s redundant sites, by acquirers, banks or other third-party providers, by you or your own suppliers, or by scheduled maintenance.

Transaction critical services are those a customer needs in order to complete a purchase. Additional services are everything that is neither transaction critical nor transaction non-critical.

Maintenance downtime

Definition	Threshold
Maximum maintenance downtime occasions	5 per year
Maximum maintenance downtime	15 hours per year
Notice given before maintenance	7 days

Status and support

Live and historical status, and subscriptions to incident updates by email, SMS or RSS, are at status.kustom.co. Scheduled maintenance is announced there too.
Support is available by email, chat and telephone from 09:00 to 17:00 on local business days, Monday to Friday. Weekend availability varies by market — check help.kustom.co.

These objectives are general guidelines for Kustom’s regional integration APIs and are public reference material, not a contract. A Service Level Agreement can be added to a partnership agreement with Kustom on request.

Handling an error your client has never seen — the default branch this page requires
Retrying when a service is temporarily unavailable — the schedule for a 5xx
Pacing a client so it stays inside quota — rate limits and their headers
Reading the generated endpoint schemas — where fields, including new ones, are documented

This page is also available as Markdown — append .md to its URL — and is indexed in llms.txt.