Data Consistency

The ODUS API is designed for high throughput and low latency. To achieve this, certain read endpoints use optimized database connections that may reflect data with a slight delay after a write operation. This page explains how consistency works across different endpoint types.

Strongly consistent endpoints

All write operations (create, update, authorize, capture, reverse, etc.) return the latest state of the resource in the response body. The returned object always reflects the most recent changes.

Retrieve-by-ID endpoints (e.g. GET /payments/:id) are also strongly consistent and always return the latest state.

POST /payments/:id/authorize  →  Returns the up-to-date Payment object
GET  /payments/:id             →  Always returns the latest state

Eventually consistent endpoints

List endpoints (e.g. GET /payments, GET /customers, GET /subscriptions) are optimized for high-volume read traffic. Under normal operating conditions, data is available on list endpoints within a few hundred milliseconds of a write. In rare cases during high load, propagation may take up to one second.

GET /payments          →  May have a brief delay after a write
GET /transactions      →  May have a brief delay after a write
GET /subscriptions     →  May have a brief delay after a write

note

This applies to all paginated list endpoints across all resources.

Response caching

Every response carrying merchant data is scoped to the key that requested it, so none of it may be cached. Those responses are returned with:

Cache-Control: no-store

They carry no ETag, and conditional requests (If-None-Match, If-Modified-Since) are ignored — every request is answered in full, and the API never replies 304 Not Modified. Configure your HTTP client, proxy, and CDN accordingly: store nothing, and re-request whenever you need current data.

The OpenAPI schema documents (/openapi.json and /openapi.v1.json) are the one exception. They are identical for every caller and change only when the API does, so they are returned with Cache-Control: no-cache and an ETag: cache them, and send If-None-Match to revalidate — you'll get a 304 Not Modified while your copy is current.

Best practices

1. Use the write response as the source of truth. After creating or updating a resource, use the response body — don't immediately poll the list endpoint.

2. Don't rely on list endpoints for read-after-write flows. If you need to confirm a payment was authorized, use the response from POST /payments/:id/authorize or retrieve it by ID with GET /payments/:id.

3. Webhooks deliver the latest state. If you receive a webhook event and need the full resource, use the retrieve-by-ID endpoint (GET /payments/:id) which is always strongly consistent.

Summary

Endpoint type	Consistency	Example
Write operations	Strong	POST /payments, POST /payments/:id/authorize
Retrieve by ID	Strong	GET /payments/:id
List (paginated)	Eventual (< 1s)	GET /payments