Data update guarantees
Strong consistency
Each resource provides read-after-write consistency for the same entity endpoint. This ensures that when a client updates an entity, the system makes the changes immediately available in the response and for subsequent queries to the same endpoint for that entity.
Example: The fulfillmenttools REST API provides this guarantee. If a client updates facility details via POST /api/facilities/{ID} and waits for the response, a subsequent GET /api/facilities/{ID} query will immediately reflect the updated state. However, a read of all facilities using GET /api/facilities/ does not guarantee that the updated facility's details will be instantly reflected, as list views or aggregated views of data may rely on eventual consistency. This restriction explicitly includes reads with specific filters or pagination parameters.
Example: In the GraphQL API, read-after-write consistency is guaranteed for root-level fields when querying an entity by its ID. For instance, if a facility's details are updated using a mutation:
mutation {
updateFacility(input: { id: "123", ... }) { ... }
}A subsequent query for the same facility will immediately reflect the updated state:
query {
facilityV2(id: "123") { ... }
}However, a query for all facilities does not guarantee that the updated facility's details will be instantly reflected, as list views or aggregated views of data may rely on eventual consistency. This restriction explicitly includes reads with specific filters or pagination parameters.
Eventual consistency
Following an update, some changes are not immediately visible in client applications (especially mobile and web clients). For example, shipment creation is an asynchronous process. While updating the shipment resource itself provides read-after-write consistency, the platform delays updating its visibility in the respective client applications. Additionally, eventual consistency is guaranteed for any list views of data, such as a list of facilities.
These delayed updates provide an eventual consistency guarantee, meaning the changes become visible after a short delay. The length of this delay can vary depending on the amount of data to be processed. The system is designed to keep these delays to a minimum.
Optimistic concurrency control (optimistic locking)
Many API resources use optimistic concurrency control to prevent lost updates when concurrently changing existing data. These resources have a version attribute. When sending an update, the client must include the last known version of the resource as part of the request. After a successful update, 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. The version number is not guaranteed to be consistently incremented.
The API does not use ETag and If-Match HTTP headers to control optimistic concurrency. Instead, it returns a 409 HTTP status (Conflict) error if a version mismatch occurs.
Last updated