Data update guarantees

Strong consistency

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

Eventual consistency

Some updates are not immediately visible 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 platform delays updating the actual visibility in said clients.

These delayed updates provide an eventual consistency guarantee. This 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 concurrently making changes to existing data. These resources have a version attribute. When sending updates to these resources, the expected (and to the client's last known version) of a resource is sent as a part of the request. After updating, the HTTP response body contains the new version of the resource.

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 to control optimistic concurrency. The API returns a 409 HTTP status (Conflict) error if a version mismatch occurs.