Amend usage
This endpoint is used to amend usage within a timeframe for a customer that has an active subscription.
This endpoint will mark all existing events within [timeframe_start, timeframe_end)
as ignored for billing
purposes, and Orb will only use the new events passed in the body of this request as the source of truth for that
timeframe moving forwards.
Note that a given time period can be amended any number of times, so events can be overwritten in subsequent calls to th
is endpoint.
This is a powerful and audit-safe mechanism to retroactively change usage data in cases where you need to:
- decrease historical usage consumption because of degraded service availability in your systems
- account for gaps from your usage reporting mechanism
- make point-in-time fixes for specific event records, while retaining the original time of usage and associated metadata. This amendment API is designed with two explicit goals:
- Amendments are always audit-safe. The amendment process will still retain original events in the timeframe, though they will be ignored for billing calculations. For auditing a nd data fidelity purposes, Orb never overwrites or permanently deletes ingested usage data.
- Amendments always preserve data consistency. In other words, either an amendment is fully processed by the system (and the new events for the timeframe are honored rather than the existing ones) or the amendment request fails. To maintain this important property, Orb prevents partial event ingestion on this endpoint.
Response semantics
- Either all events are ingested successfully, or all fail to ingest (returning a
4xx
or5xx
response code). - Any event that fails schema validation will lead to a
4xx
response. In this case, to maintain data consistency, Orb will not ingest any events and will also not deprecate existing events in the time period. - You can assume that the amendment is successful on receipt of
a
2xx
response.While a successful response from this endpoint indicates that the new events have been ingested, updating usage totals happens asynchronously and may be delayed by a few minutes.
As emphasized above, Orb will never show an inconsistent state (e.g. in invoice previews or dashboards); either it will show the existing state (before the amendment) or the new state (with new events in the requested timeframe).
Sample request body
{
"events": [{
"event_name": "payment_processed",
"timestamp": "2022-03-24T07:15:00Z",
"properties": {
"amount": 100
}
}, {
"event_name": "payment_failed",
"timestamp": "2022-03-24T07:15:00Z",
"properties": {
"amount": 100
}
}]
}
Request Validation
The
timestamp
of each event reported must fall within the bounds oftimeframe_start
andtimeframe_end
. As with ingestion, all timesta mps must be sent in ISO8601 format with UTC timezone offset.Orb does not accept an
idempotency_key
with each event in this endpoint, since the entirety of the event list must be ingested to ensure consistency. On retryable errors , you should retry the request in its entirety, and assume that the amendment operation has not succeeded until receipt of a2xx
.Both
timeframe_start
andtimeframe_end
must be timestamps in the past. Furthermore, Orb will genera lly validate that thetimeframe_start
andtimeframe_end
fall within the customer's current subscription billing pe riod. However, Orb does allow amendments while in the grace period of the previous billing period; in this instance, the timeframe can start before the current period.
API Limits
Note that Orb does not currently enforce a hard rate- limit for API usage or a maximum request payload size. Similar to the event ingestion API, this API is architected for h igh-throughput ingestion. It is also safe to programmatically call this endpoint if your system can automatically dete ct a need for historical amendment.
In order to overwrite timeframes with a very large number of events, we suggest using multiple calls with small adjacent (e.g. every hour) timeframes.
Path Parameters
Query Parameters
Request Body
- Array [
- ]
events object[] required
Events to update
The Orb Customer identifier
An alias for the Orb customer, whose mapping is specified when creating the customer
A name to meaningfully identify the action or event type.
An ISO 8601 format date with no timezone offset (i.e. UTC). This should represent the time that usage was recorded, and is particularly important to attribute usage to a given billing period.
A dictionary of custom properties. Values in this dictionary must be numeric, boolean, or strings. Nested dictionaries are disallowed.
- 200
- 400
- 401
- 404
- 409
- 413
- 429
- 500
OK
Response Headers
Schema
An array of strings, corresponding to idempotency_key's marked as duplicates (previously ingested)
An array of strings, corresponding to idempotency_key's which were successfully ingested.
{
"duplicate": [
"string"
],
"ingested": [
"string"
]
}
Bad Request
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#400-constraint-violation
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#400-duplicate-resource-creation
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#400-request-validation-errors
]
Possible values: [400
]
{}
Unauthorized
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#401-authentication-error
]
Possible values: [401
]
{
"type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
"status": 401,
"detail": "string",
"title": "string"
}
Not Found
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#404-feature-not-available
]
Possible values: [400
]
Possible values: [https://docs.withorb.com/reference/error-responses#404-resource-not-found
]
Possible values: [404
]
Possible values: [https://docs.withorb.com/reference/error-responses#404-url-not-found
]
Possible values: [404
]
{}
Conflict
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#409-resource-conflict
]
Possible values: [409
]
{
"type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
"status": 409,
"detail": "string",
"title": "string"
}
Request Entity Too Large
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#413-request-too-large
]
Possible values: [413
]
Possible values: [https://docs.withorb.com/reference/error-responses#413-resource-too-large
]
Possible values: [413
]
Possible values: [https://docs.withorb.com/reference/error-responses#413-too-many-results
]
Possible values: [413
]
{}
Too Many Requests
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#429-too-many-requests
]
Possible values: [429
]
{
"type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
"status": 429,
"detail": "string",
"title": "string"
}
Internal Server Error
Response Headers
Schema
Possible values: [https://docs.withorb.com/reference/error-responses#500-internal-server-error
]
{
"type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
"status": 0,
"detail": "string",
"title": "string"
}