Read consistency

The Chargebee API supports two kinds of read operations:

• Retrieve operations return a single resource. For example, Retrieve a customer.
• List operations return a collection of resources. For example, List customers and List subscriptions.

Each kind provides a different read consistency guarantee.

Strongly consistent reads

Retrieve operations, and other single-resource GET endpoints, are strongly consistent. When you call a retrieve endpoint, Chargebee returns the current state of the resource, including every write that completed before the request.

Retrieve operations therefore let you read your own writes: you can call a retrieve endpoint immediately after a create or update call and treat the response as the current state of the resource. For example, you can read a subscription right after you change its plan, or a customer right after you update their billing address.

Eventually consistent reads

List operations, and other collection GET endpoints that accept limit and offset pagination, are eventually consistent. A response from these endpoints might not reflect a recent write.

List operations query across many resources instead of reading a single item. They accept a short delay in freshness in exchange for efficient pagination and filtering at scale.

Eventual consistency affects your integration in two ways:

• A new or updated resource might not appear in a list response immediately after the write that created or changed it.
• A filtered or sorted query, such as GET /subscriptions?status[is]=active or GET /invoices?customer_id[is]=cust_123, might return a resource's earlier state instead of its latest state.

Best practices

• Use retrieve operations to read your own writes. To verify the exact state that you wrote, call the retrieve endpoint for that resource instead of a list endpoint.
• Don't treat list operations as a source of truth for time-sensitive checks. For example, to check whether an invoice's status has changed, call the retrieve endpoint for that invoice, or wait for the webhook event and then confirm with a retrieve call.
• For data synchronization, use list operations. To sync data periodically, such as to a data warehouse, follow the incremental syncing algorithm. Its overlapping time window is designed to pick up resources that an earlier sync missed.