# 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`](/api/errors/) 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](https://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](https://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.

## Related

- [Handling an error your client has never seen](/api/errors/) — the default branch this page requires
- [Retrying when a service is temporarily unavailable](/order-management/idempotency-and-retries/) — the schedule for a 5xx
- [Pacing a client so it stays inside quota](/api/limits/) — rate limits and their headers
- [Reading the generated endpoint schemas](/api/checkout/) — where fields, including new ones, are documented