Cached usage responses
Orb features several API endpoints to query usage data for a given Subscription or Customer. It's common to use these in order to power dashboards or views in your own application, allowing your end users to see their current or historical usage.
Orb's data architecture is designed to give you usage results performantly, and the default implementations of usage fetching endpoints prioritize data freshness over latency.
When it's more important to fetch data quickly which may not capture the latest usage, Orb provides the ability for you to query cached results. By default, Orb does not recompute data when it's known to be fresh, and also provides an explicit opt-in feature to use cached and potentially stale data. We recommend using this in cases where you plan to render a chart or preview on page load, allowing you to build an interaction where the latest data is loaded asynchronously if necessary.
The performance difference between fetching cached and live data depends on the number and cost of queries against the events datastore that would otherwise be required. In most cases, you should expect at a 1.5-2x speedup in latency.
Supported endpoints
The currently supported endpoints are:
/v1/subscriptions/<subscription_id>/usage/v1/subscriptions/<subscription_id>/costs/v1/customers/<customer_id>/costs/v1/customers/external_customer_id/<external_customer_id>/costs/v1/invoices/upcoming/v1/invoices/<invoice_id>- Note: Performance benefits are only expected on invoices with
status = 'draft'
- Note: Performance benefits are only expected on invoices with
Header Semantics
Orb currently supports two approaches for requesting cached data.
Always fetching cached data
In order to opt-in to cached data, explicitly pass the following case-sensitive header:
| Key | Value |
|---|---|
Orb-Cache-Control | cache |
Fetch cached data conditional on a staleness threshold
In order to conditionally opt-in to cached data based on a maximum staleness age, pass the following headers:
| Key | Value |
|---|---|
Orb-Cache-Control | cache |
Orb-Cache-Max-Age-Seconds | <staleness_threshold_seconds> (int) |
The staleness of the cache is determined based on Orb's invalidation based architecture, which tracks any potentially material changes to an Orb customer. Material changes include (but are not limited to) events ingested, subscription lifecycle changes, and prepurchase balance adjustments. Upon receiving an invalidating event, Orb marks a customer as invalid and schedules processing in the near future to rehydrate the cache.
Response headers
On HTTP 200 responses when the Orb-Cache-Control header is passed with or without Orb-Cache-Max-Age-Seconds, the response will return the following
header:
| Key | Value |
|---|---|
Orb-Cache-Updated-At | ISO timestamp string (e.g. 2024-02-14T06:48:26.366184+00:00) |
In "always fetch cached" scenarios, We recommend using the Orb-Cache-Updated-At value to determine if a follow-up request is necessary. If a specific result is completely up to date (based on internal event ingestion invalidation markers), Orb will set this value to the current time.