Update Guarantees

The API provides different update guarantees for different kinds of requests.

Strong Consistency

Each resource provides read-after-write consistency. Read-after-write consistency means that when an entity is updated, the changes that were made are instantly available after waiting for the successful response and reading the same entity.

Eventual Consistency

Some updates are not visible immediately in the used clients (especially mobile and web clients) after the update. For example, if a shipment was created which is by design an asynchronous process, updating the shipment itself provides read-after-write consistency, but the actual visibility in said clients is updated with a delay by the platform.

These delayed updates provide an Eventual Consistency guarantee. It means that after a delay you will be able to see the changes that you or a follow up process performed.

These delays can vary depending on the amount of data to update. We try to keep these delays as small as possible.

Optimistic Concurrency Control (Optimistic Locking)

Many API resources use optimistic concurrency control to prevent lost updates when making changes to existing data concurrently. These resources have a version attribute. When sending (partial) updates to these resources, the expected (and to the client last known version) of a resource is sent as a part of the request.

After making an update, the HTTP response body contains the new version of the resource. An API client must wait for the new version before sending follow-up requests.

Background processes and other events can also change a resource’s version number without any requests sent from an API client directly to the resource. Do not rely on a consistently incremented version number.

The API does not use ETag and If-Match HTTP headers for the purpose of optimistic concurrency control.

If a version mismatch occurs, the API returns a 409 HTTP status (Conflict) error.