Architecture principles

Integrating with Orb

Overview

Core concepts

Authentication

Postman

Timezone localization

Dry run requests

Preview side effects

Pending changes

Ingest events

Integrate with cloud storage

Segment integration

Construct metrics

Customer aliases

Hosted rollups

Querying data with SQL

Backfill and amend events

Configuring plans

Price configuration

Creating subscriptions

Modifying subscriptions

Configure prepaid credits

Executing a price change

View subscription usage

Customer hierarchy

Configure cost, usage, and balance alerts and understand their evaluation SLAs.

Alerting overview

Configure cost and usage‑based alerts at the plan or individual subscription level.

Subscription alerts

Detect when a customer’s prepaid‑credit balance is depleted, drops below a threshold, or recovers.

Balance alerts

Use alerts and limits to help customers manage and cap their spend.

Spend management

Introduction

Structure and lifecycle

Invoice calculations

Payments and collection

Invoice portal

Invoice delivery

Invoice display

One-off invoices

Threshold Invoicing

Credit notes

Best practices

Financial analyses using Orb data

Exported resource types

Advanced metrics

Custom pricing

Create a billable metric

Configure your pricing

Manage subscriptions

Invoice your customers

Set up prepaid credits

Pricing an AI agent

Product access with prepaid credits

Request idempotency

Pagination

Error responses

Rate limits

Reliability and scaling

Cached usage responses

This endpoint returns a list of alerts within Orb.

The request must specify one of `customer_id`, `external_customer_id`, or `subscription_id`.

If querying by subscripion_id, the endpoint will return the subscription level alerts as well as the plan level alerts
associated with the subscription.

The list of alerts is ordered starting from the most recently created alert.
This endpoint follows Orb's [standardized pagination format](/api-reference/pagination).

List alerts

 This endpoint creates a new alert to monitor a customer's credit balance. There are three types of alerts that can be scoped to
 customers: `credit_balance_depleted`, `credit_balance_dropped`, and `credit_balance_recovered`. Customers can have a maximum
 of one of each type of alert per [credit balance currency](/product-catalog/prepurchase).
`credit_balance_dropped` alerts require a list of thresholds to be provided while `credit_balance_depleted`
 and `credit_balance_recovered` alerts do not require thresholds.

Create customer alert

Create customer alert by external ID

This endpoint is used to create alerts at the subscription level.

Subscription level alerts can be one of two types: `usage_exceeded` or `cost_exceeded`. A `usage_exceeded` alert is
scoped to a particular metric and is triggered when the usage of that metric exceeds predefined thresholds during the
current billing cycle. A `cost_exceeded` alert is triggered when the total amount due during the current billing cycle surpasses
predefined thresholds. `cost_exceeded` alerts do not include burndown of pre-purchase credits. Each subscription can have one
`cost_exceeded` alert and one `usage_exceeded` alert per metric that is a part of the subscription. Alerts are triggered based
on usage or cost conditions met during the current billing cycle.

Create subscription alert

This endpoint updates the thresholds of an alert.

Update alert

This endpoint allows you to disable an alert. To disable a plan-level alert for a specific subscription, you must include
the `subscription_id`. The `subscription_id` is not required for customer or subscription level alerts.

Disable alert by ID

This endpoint allows you to enable an alert. To enable a plan-level alert for a specific subscription, you must include
the `subscription_id`. The `subscription_id` is not required for customer or subscription level alerts.

Enable alert by ID

This endpoint retrieves an alert by its ID.

Fetch alert

This endpoint returns a list of all coupons for an account in a list format.

The list of coupons is ordered starting from the most recently created coupon. The response also includes
`pagination_metadata`, which lets the caller retrieve the next page of results if they exist. More information
about pagination can be found in the Pagination-metadata schema.

List coupons

This endpoint allows the creation of coupons, which can then be redeemed at subscription creation or plan change.

Create coupon

This endpoint retrieves a coupon by its ID. To fetch coupons by their redemption code, use the
[List coupons](list-coupons) endpoint with the redemption_code parameter.

Fetch coupon

This endpoint allows a coupon to be archived. Archived coupons can no longer be redeemed, and
will be hidden from lists of active coupons. Additionally, once a coupon is archived, its redemption
code can be reused for a different coupon.

Archive coupon

This endpoint returns a list of all subscriptions that have redeemed a given coupon as a
[paginated](/api-reference/pagination) list, ordered starting from the most recently created subscription. For a full
discussion of the subscription resource, see [Subscription](/core-concepts#subscription).

List coupon subscriptions

Get a paginated list of CreditNotes. Users can also filter by
customer_id, subscription_id, or external_customer_id. The credit notes will be returned
in reverse chronological order by `creation_time`.

List credit notes

This endpoint is used to create a single [`Credit Note`](/invoicing/credit-notes).

Create credit note

This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes) given an identifier.

Fetch credit note

This endpoint returns a list of all customers for an account.
The list of customers is ordered starting from the most recently created customer.
This endpoint follows Orb's [standardized pagination format](/api-reference/pagination).

See [Customer](/core-concepts##customer) for an overview of the customer model.

List customers

This operation is used to create an Orb customer, who is party to the core billing relationship. See
[Customer](/core-concepts##customer) for an overview of the customer resource.

This endpoint is critical in the following Orb functionality:
* Automated charges can be configured by setting `payment_provider` and `payment_provider_id` to automatically
  issue invoices
* [Customer ID Aliases](/events-and-metrics/customer-aliases) can be configured by setting
  `external_customer_id`
* [Timezone localization](/essentials/timezones) can be configured on a per-customer basis by
  setting the `timezone` parameter

Create customer

This endpoint is used to fetch customer details given an `external_customer_id` (see
[Customer ID Aliases](/events-and-metrics/customer-aliases)).

Note that the resource and semantics of this endpoint exactly mirror [Get Customer](fetch-customer).

Fetch customer by external ID

This endpoint is used to update customer details given an `external_customer_id`
(see [Customer ID Aliases](/events-and-metrics/customer-aliases)).
Note that the resource and semantics of this endpoint exactly mirror [Update Customer](update-customer).

Update customer by external ID

This endpoint is used to fetch a day-by-day snapshot of a customer's costs in Orb, calculated by applying pricing
information to the underlying usage (see the [subscription usage endpoint](/api-reference/subscription/fetch-subscription-usage)
to fetch usage per metric, in usage units rather than a currency).

This endpoint can be leveraged for internal tooling and to provide a more transparent billing experience for your
end users:

1. Understand the cost breakdown per line item historically and in real-time for the current billing period.
2. Provide customer visibility into how different services are contributing to the overall invoice with a per-day
  timeseries (as compared to the [upcoming invoice](/api-reference/invoice/fetch-upcoming-invoice) resource,
  which represents a snapshot for the current period).
3. Assess how minimums and discounts affect your customers by teasing apart costs directly as a result of usage,
  as opposed to minimums and discounts at the plan and price level.
4. Gain insight into key customer health metrics, such as the percent utilization of the minimum committed spend.

## Fetching subscriptions
By default, this endpoint fetches the currently active subscription for the customer, and returns cost information
for the subscription's current billing period, broken down by each participating price. If there are no currently
active subscriptions, this will instead default to the most recently active subscription or return an empty series
if none are found. For example, if your plan charges for compute hours, job runs, and data syncs, then this endpoint
would provide a daily breakdown of your customer's cost for each of those axes.

If timeframe bounds are specified, Orb fetches all subscriptions that were active in that timeframe. If two
subscriptions overlap on a single day, costs from each price will be summed, and prices for both subscriptions will
be included in the breakdown.

## Prepaid plans
For plans that include prices which deduct credits rather than accrue in-arrears charges in a billable currency,
this endpoint will return the total deduction amount, in credits, for the specified timeframe.

## Cumulative subtotals and totals
Since the subtotal and total must factor in any billing-period level discounts and minimums, it's most meaningful
to consider costs relative to the start of the subscription's billing period. As a result, by default this endpoint
returns cumulative totals since the beginning of the billing period. In particular, the `timeframe_start` of a
returned timeframe window is *always* the beginning of the billing period and `timeframe_end` is incremented one day
at a time to build the result.

A customer that uses a few API calls a day but has a minimum commitment might exhibit the following pattern for
their subtotal and total in the first few days of the month. Here, we assume that each API call is $2.50, the
customer's plan has a monthly minimum of $50 for this price, and that the subscription's billing period bounds are
aligned to the first of the month:

| timeframe_start | timeframe_end | Cumulative usage | Subtotal | Total (incl. commitment)  |
| -----------| ----------- | ----------- | ----------- |----------- |
| 2023-02-01 | 2023-02-02 | 9 | $22.50 | $50.00 |
| 2023-02-01 | 2023-02-03 | 19 | $47.50 | $50.00 |
| 2023-02-01 | 2023-02-04 | 20 | $50.00 | $50.00 |
| 2023-02-01 | 2023-02-05 | 28 | $70.00 | $70.00 |
| 2023-02-01 | 2023-02-06 | 36 | $90.00 | $90.00 |

### Periodic values
When the query parameter `view_mode=periodic` is specified, Orb will return an incremental day-by-day view of costs.
In this case, there will always be a one-day difference between `timeframe_start` and `timeframe_end` for the
timeframes returned. This is a transform on top of the cumulative costs, calculated by taking the difference of each
timeframe with the last. Note that in the above example, the `Total` value would be 0 for the second two data
points, since the minimum commitment has not yet been hit and each day is not contributing anything to the total
cost.

## Timeframe bounds
For an active subscription, both timeframes should be specified in the request. If a subscription starts or ends within the
timeframe, the response will only include windows where the subscription is active. If a subscription has ended, no timeframe
bounds need to be specified and the response will default to the billing period when the subscription was last active.

As noted above, `timeframe_start` for a given cumulative datapoint is always the beginning of the billing period,
and `timeframe_end` is incremented one day at a time to construct the response. When a timeframe is passed in that
is not aligned to the current subscription's billing period, the response will contain cumulative totals from
multiple billing periods.

Suppose the queried customer has a subscription aligned to the 15th of every month. If this endpoint is queried with
the date range `2023-06-01` - `2023-07-01`, the first data point will represent about half a billing period's worth
of costs, accounting for accruals from the start of the billing period and inclusive of the first day of the
timeframe (`timeframe_start = 2023-05-15 00:00:00`, `timeframe_end = 2023-06-02 00:00:00`)

| datapoint index | timeframe_start | timeframe_end |
| ----------- | -----------| ----------- |
| 0 | 2023-05-15 | 2023-06-02 |
| 1 | 2023-05-15 | 2023-06-03 |
| 2 | ... | ... |
| 3 | 2023-05-15 | 2023-06-14 |
| 4 | 2023-06-15 | 2023-06-16 |
| 5 | 2023-06-15 | 2023-06-17 |
| 6 | ... | ... |
| 7 | 2023-06-15 | 2023-07-01 |

You can see this sliced timeframe visualized [here](https://i.imgur.com/TXhYgme.png).

### Matrix prices
When a price uses matrix pricing, it's important to view costs grouped by those matrix dimensions. Orb will return
`price_groups` with the `grouping_key` and `secondary_grouping_key` based on the matrix price definition, for each
`grouping_value` and `secondary_grouping_value` available.

Fetch customer costs by external ID

Sync Orb's payment methods for the customer with their gateway.

This method can be called before taking an action that may cause the customer to be charged, ensuring that the most up-to-date
payment method is charged.

**Note**: This functionality is currently only available for Stripe.

Update payment methods from payment provider

This endpoint is used to fetch customer details given an identifier. If the `Customer` is in the process of being deleted,
only the properties `id` and `deleted: true` will be returned.

See the [Customer resource](/core-concepts#customer) for a full discussion of the Customer model.

Fetch customer

This endpoint can be used to update the `payment_provider`, `payment_provider_id`, `name`, `email`, `email_delivery`, `tax_id`,
`auto_collection`, `metadata`, `shipping_address`, `billing_address`, and `additional_emails` of an existing customer.
Other fields on a customer are currently immutable.

Update customer

This performs a deletion of this customer, its subscriptions, and its invoices, provided the customer does not have any issued
invoices. Customers with issued invoices cannot be deleted. This operation is irreversible. Note that this
is a _soft_ deletion, but the data will be inaccessible through the API and Orb dashboard.

For a hard-deletion, please reach out to the Orb team directly.

**Note**: This operation happens asynchronously and can be expected to take a
few minutes to propagate to related resources. However, querying for the customer on
subsequent GET requests while deletion is in process will reflect its deletion.

Delete customer

## The customer balance

The customer balance is an amount in the customer's currency, which Orb automatically applies to subsequent
invoices. This balance can be adjusted manually via Orb's webapp on the customer details page. You can use this
balance to provide a fixed mid-period credit to the customer. Commonly, this is done due to system downtime/SLA
violation, or an adhoc adjustment discussed with the customer.

If the balance is a positive value at the time of invoicing, it represents that the customer has credit that should
be used to offset the amount due on the next issued invoice. In this case, Orb will automatically reduce the next
invoice by the balance amount, and roll over any remaining balance if the invoice is fully discounted.

If the balance is a negative value at the time of invoicing, Orb will increase the invoice's amount due with a
positive adjustment, and reset the balance to 0.

This endpoint retrieves all customer balance transactions in reverse chronological order for a single customer,
providing a complete audit trail of all adjustments and invoice applications.

List balance transactions

Creates an immutable balance transaction that updates the customer's balance and returns back the newly created
transaction.

Create customer balance transaction

Fetch customer costs

Returns a paginated list of unexpired, non-zero credit blocks for a customer.

If `include_all_blocks` is set to `true`, all credit blocks (including expired and depleted blocks) will be included in
the response.

Note that `currency` defaults to credits if not specified. To use a real world currency, set `currency` to an ISO 4217 string.

Fetch customer credit balance by external customer id

The credits ledger provides _auditing_ functionality over Orb's credits system with a list of actions that have
taken place to modify a customer's credit balance. This [paginated endpoint](/api-reference/pagination) lists these
entries, starting from the most recent ledger entry.

More details on using Orb's real-time credit feature are [here](/product-catalog/prepurchase).

There are four major types of modifications to credit balance, detailed below.

## Increment
Credits (which optionally expire on a future date) can be added via the API
([Add Ledger Entry](create-ledger-entry)). The ledger entry for such an action will always contain the total
eligible starting and ending balance for the customer at the time the entry was added to the ledger.

## Decrement
Deductions can occur as a result of an API call to create a ledger entry (see
[Add Ledger Entry](create-ledger-entry)), or automatically as a result of incurring usage. Both ledger entries
present the `decrement` entry type.

As usage for a customer is reported into Orb, credits may be deducted according to the customer's plan
configuration. An automated deduction of this type will result in a ledger entry, also with a starting and ending
balance. In order to provide better tracing capabilities for automatic deductions, Orb always associates each
automatic deduction with the `event_id` at the time of ingestion, used to pinpoint _why_ credit deduction took
place and to ensure that credits are never deducted without an associated usage event.

By default, Orb uses an algorithm that automatically deducts from the *soonest expiring credit block* first in
order to ensure that all credits are utilized appropriately. As an example, if trial credits with an expiration date
of 2 weeks from now are present for a customer, they will be used before any deductions take place from a
non-expiring credit block.

If there are multiple blocks with the same expiration date, Orb will deduct from the block with the
*lower cost basis* first (e.g. trial credits with a $0 cost basis before paid credits with a $5.00 cost basis).

It's also possible for a single usage event's deduction to _span_ credit blocks. In this case, Orb will deduct from
the next block, ending at the credit block which consists of unexpiring credits. Each of these deductions will lead
to a _separate_ ledger entry, one per credit block that is deducted from. By default, the customer's total credit
balance in Orb can be negative as a result of a decrement.

## Expiration change
The expiry of credits can be changed as a result of the API (See [Add Ledger Entry](create-ledger-entry)). This will
create a ledger entry that specifies the balance as well as the initial and target expiry dates.

Note that for this entry type, `starting_balance` will equal `ending_balance`, and the `amount` represents the
balance transferred. The credit block linked to the ledger entry is the source credit block from which there was an
expiration change

## Credits expiry
When a set of credits expire on pre-set expiration date, the customer's balance automatically reflects this change
and adds an entry to the ledger indicating this event. Note that credit expiry should always happen close to a date
boundary in the customer's timezone.

## Void initiated
Credit blocks can be voided via the API. The `amount` on this entry corresponds to the number of credits that were
remaining in the block at time of void. `void_reason` will be populated if the void is created with a reason.

## Void
When a set of credits is voided, the customer's balance automatically reflects this change and adds an entry to the
ledger indicating this event.

## Amendment
When credits are added to a customer's balance as a result of a correction, this entry will be added to the ledger
to indicate the adjustment of credits.

Fetch customer credits ledger by external ID

This endpoint allows you to create a new ledger entry for a specified customer's balance. This can be used to
increment balance, deduct credits, and change the expiry date of existing credits.

## Effects of adding a ledger entry
1. After calling this endpoint, [Fetch Credit Balance](fetch-customer-credits) will return a credit block that
  represents the changes (i.e. balance changes or transfers).
2. A ledger entry will be added to the credits ledger for this customer, and therefore returned in the
  [View Credits Ledger](fetch-customer-credits-ledger) response as well as serialized in the response to this request. In
  the case of deductions without a specified block, multiple ledger entries may be created if the deduction spans
  credit blocks.
3. If `invoice_settings` is specified, an invoice will be created that reflects the cost of the credits (based on
  `amount` and `per_unit_cost_basis`).

## Adding credits
  Adding credits is done by creating an entry of type `increment`. This requires the caller to specify a number of
  credits as well as an optional expiry date in `YYYY-MM-DD` format. Orb also recommends specifying a description
  to assist with auditing. When adding credits, the caller can also specify a cost basis per-credit, to indicate
  how much in USD a customer paid for a single credit in a block. This can later be used for revenue recognition.

The following snippet illustrates a sample request body to increment credits which will expire in January of 2022.

```json
{
  "entry_type": "increment",
  "amount": 100,
  "expiry_date": "2022-12-28",
  "per_unit_cost_basis": "0.20",
  "description": "Purchased 100 credits"
}
```

Note that by default, Orb will always first increment any _negative_ balance in existing blocks before adding the
remaining amount to the desired credit block.

### Invoicing for credits
By default, Orb manipulates the credit ledger but does not charge for credits. However, if you pass
`invoice_settings` in the body of this request, Orb will also generate a one-off invoice for the customer for the
credits pre-purchase. Note that you _must_ provide the `per_unit_cost_basis`, since the total charges on the
invoice are calculated by multiplying the cost basis with the number of credit units added.

## Deducting Credits
Orb allows you to deduct credits from a customer by creating an entry of type `decrement`. Orb matches the
algorithm for automatic deductions for determining which credit blocks to decrement from. In the case that the
deduction leads to multiple ledger entries, the response from this endpoint will be the final deduction. Orb also
optionally allows specifying a description to assist with auditing.

The following snippet illustrates a sample request body to decrement credits.

```json
{
  "entry_type": "decrement",
  "amount": 20,
  "description": "Removing excess credits"
}
```

## Changing credits expiry
If you'd like to change when existing credits expire, you should create a ledger entry of type `expiration_change`.
For this entry, the required parameter `expiry_date` identifies the _originating_ block, and the required parameter
`target_expiry_date` identifies when the transferred credits should now expire. A new credit block will be created
with expiry date `target_expiry_date`, with the same cost basis data as the original credit block, if present.

Note that the balance of the block with the given `expiry_date` must be at least equal to the desired transfer
amount determined by the `amount` parameter.

The following snippet illustrates a sample request body to extend the expiration date of credits by one year:

```json
{
  "entry_type": "expiration_change",
  "amount": 10,
  "expiry_date": "2022-12-28",
  "block_id": "UiUhFWeLHPrBY4Ad",
  "target_expiry_date": "2023-12-28",
  "description": "Extending credit validity"
}
```

## Voiding credits

If you'd like to void a credit block, create a ledger entry of type `void`. For this entry, `block_id` is required
to identify the block, and `amount` indicates how many credits to void, up to the block's initial balance. Pass
in a `void_reason` of `refund` if the void is due to a refund.

## Amendment

If you'd like to undo a decrement on a credit block, create a ledger entry of type `amendment`. For this entry, `block_id`
is required to identify the block that was originally decremented from, and `amount` indicates how many credits to return
to the customer, up to the block's initial balance.

Create ledger entry by external ID

List top-ups by external ID

This endpoint allows you to create a new top-up for a specified customer's balance.
While this top-up is active, the customer's balance will added in increments of
the specified amount whenever the balance reaches the specified threshold.

If a top-up already exists for this customer in the same currency,
the existing top-up will be replaced.

Create top-up by external ID

This deactivates the top-up and voids any invoices associated with pending credit blocks purchased through the top-up.

Deactivate top-up by external ID

Fetch customer credit balance

Fetch customer credits ledger

Create ledger entry

List top-ups

Create top-up

Deactivate top-up

List dimensional price groups

A dimensional price group is used to partition the result of a billable metric by a set of dimensions. Prices in a
price group must specify the parition used to derive their usage.

For example, suppose we have a billable metric that measures the number of widgets used and we want to charge differently
depending on the color of the widget. We can create a price group with a dimension "color" and two prices: one that
charges \$10 per red widget and one that charges \$20 per blue widget.

Create dimensional price group

Fetch dimensional price group by external ID

Fetch dimensional price group

This endpoint returns a list of all backfills in a list format.

The list of backfills is ordered starting from the most recently created backfill. The response also includes
[`pagination_metadata`](/api-reference/pagination), which lets the caller retrieve the next page of results if they
exist. More information about pagination can be found in the [Pagination-metadata schema](pagination).

List backfills

Creating the backfill enables adding or replacing past events, even those that are older than the ingestion grace
period. Performing a backfill in Orb involves 3 steps:

1. Create the backfill, specifying its parameters.
2. [Ingest](ingest) usage events, referencing the backfill (query parameter `backfill_id`).
3. [Close](close-backfill) the
backfill, propagating the update in past usage throughout Orb.

Changes from a backfill are not reflected until the
backfill is closed, so you won’t need to worry about your customers seeing partially updated usage data. Backfills are
also reversible, so you’ll be able to revert a backfill if you’ve made a mistake.

This endpoint will return a
backfill object, which contains an `id`. That `id` can then be used as the `backfill_id` query parameter to the event
ingestion endpoint to associate ingested events with this backfill. The effects (e.g. updated usage graphs) of this
backfill will not take place until the backfill is closed.

If the `replace_existing_events` is `true`, existing
events in the backfill's timeframe will be replaced with the newly ingested events associated with the backfill. If
`false`, newly ingested events will be added to the existing events.

If a `customer_id` or `external_customer_id` is specified, the backfill will only affect events for that customer.
If neither is specified, the backfill will affect all customers.

When `replace_existing_events` is `true`, this indicates that existing events in the timeframe should no longer be counted
towards invoiced usage. In this scenario, the parameter `filter` can be optionally added which enables filtering using
[computed properties](/extensibility/advanced-metrics#computed-properties). The expressiveness of computed properties
allows you to deprecate existing events based on both a period of time and specific property values.

Create backfill

This endpoint is used to fetch a backfill given an identifier.

Fetch backfill

Closing a backfill makes the updated usage visible in Orb. Upon closing a backfill, Orb will asynchronously reflect
the updated usage in invoice amounts and usage graphs. Once all of the updates are complete, the backfill's status
will transition to `reflected`.

Close backfill

Reverting a backfill undoes all the effects of closing the backfill. If the backfill is reflected, the status will
transition to `pending_revert` while the effects of the backfill are undone. Once all effects are undone, the
backfill will transition to `reverted`.

If a backfill is reverted before its closed, no usage will be updated as a result of the backfill and it will
immediately transition to `reverted`.

Revert backfill

This endpoint returns a filtered set of events for an account in a [paginated list format](/api-reference/pagination).

Note that this is a `POST` endpoint rather than a `GET` endpoint because it employs a JSON body for search criteria
rather than query parameters, allowing for a more flexible search syntax.

Note that a search criteria _must_ be specified. Currently, Orb supports the following criteria:
- `event_ids`: This is an explicit array of IDs to filter by. Note that an event's ID is the `idempotency_key` that
  was originally used for ingestion.

By default, Orb will not throw a `404` if no events matched, Orb will return an empty array for `data` instead.

Search events

This endpoint returns the event volume for an account in a [paginated list format](/api-reference/pagination).

The event volume is aggregated by the hour and the [timestamp](/api-reference/event/ingest-events)
field is used to determine which hour an event is associated with. Note, this means that late-arriving events
increment the volume count for the hour window the timestamp is in, not the latest hour window.

Each item in the response contains the count of events aggregated by the hour
where the start and end time are hour-aligned and in UTC. When a specific timestamp is passed
in for either start or end time, the response includes the hours the timestamp falls in.

Get event volume

This endpoint is used to amend a single usage event with a given `event_id`. `event_id` refers to the
`idempotency_key` passed in during ingestion. The event will maintain its existing `event_id` after the amendment.

This endpoint will mark the existing event as ignored, and Orb will only use the new event passed in the body of
this request as the source of truth for that `event_id`. Note that a single event can be amended any number of
times, so the same event can be overwritten in subsequent calls to this endpoint. Only a single event with a given
`event_id` will be considered the source of truth at any given time.

This is a powerful and audit-safe mechanism to retroactively update a single event in cases where you need to:
* update an event with new metadata as you iterate on your pricing model
* update an event based on the result of an external API call (e.g. call to a payment gateway succeeded or failed)

This amendment API is always audit-safe. The process will still retain the original event, though it will be
ignored for billing calculations. For auditing and data fidelity purposes, Orb never overwrites or permanently
deletes ingested usage data.

## Request validation
* The `timestamp` of the new event must match the `timestamp` of the existing event already ingested. As with
  ingestion, all timestamps must be sent in ISO8601 format with UTC timezone offset.
* The `customer_id` or `external_customer_id` of the new event must match the `customer_id` or
  `external_customer_id` of the existing event already ingested. Exactly one of `customer_id` and
  `external_customer_id` should be specified, and similar to ingestion, the ID must identify a Customer resource
  within Orb. Unlike ingestion, for event amendment, we strictly enforce that the Customer must be in the Orb
  system, even during the initial integration period. We do not allow updating the `Customer` an event is
  associated with.
* Orb does not accept an `idempotency_key` with the event in this endpoint, since this request is by design
  idempotent. On retryable errors, you should retry the request and assume the amendment operation has not
  succeeded until receipt of a 2xx.
* The event's `timestamp` must fall within the customer's current subscription's billing period, or within the
  grace period of the customer's current subscription's previous billing period.
* By default, no more than 100 events can be amended for a single customer in a 100 day period. For higher volume
  updates, consider using the [event backfill](create-backfill) endpoint.

Amend event

This endpoint is used to deprecate a single usage event with a given `event_id`. `event_id` refers to the
`idempotency_key` passed in during ingestion.

This endpoint will mark the existing event as ignored. Note that if you attempt to re-ingest an event with the same
`event_id` as a deprecated event, Orb will return an error.

This is a powerful and audit-safe mechanism to retroactively deprecate a single event in cases where you need to:
* no longer bill for an event that was improperly reported
* no longer bill for an event based on the result of an external API call (e.g. call to a payment gateway failed and
  the user should not be billed)

If you want to only change specific properties of an event, but keep the event as part of the billing calculation,
use the [Amend event](amend-event) endpoint instead.

This API is always audit-safe. The process will still retain the deprecated event, though it will be ignored for
billing calculations. For auditing and data fidelity purposes, Orb never overwrites or permanently deletes ingested
usage data.

## Request validation
* Orb does not accept an `idempotency_key` with the event in this endpoint, since this request is by design
  idempotent. On retryable errors, you should retry the request and assume the deprecation operation has not
  succeeded until receipt of a 2xx.
* The event's `timestamp` must fall within the customer's current subscription's billing period, or within the
  grace period of the customer's current subscription's previous billing period. Orb does not allow deprecating
  events for billing periods that have already invoiced customers.
* The `customer_id` or the `external_customer_id` of the original event ingestion request must identify a Customer
  resource within Orb, even if this event was ingested during the initial integration period. We do not allow
  deprecating events for customers not in the Orb system.
* By default, no more than 100 events can be deprecated for a single customer in a 100 day period. For higher volume
  updates, consider using the [event backfill](create-backfill) endpoint.

Deprecate event

Orb's event ingestion model and API is designed around two core principles:

1. **Data fidelity**: The accuracy of your billing model depends on a robust foundation of events. Orb's API protocol
encourages usage patterns that ensure that your data is consistently complete and correct.
2. **Fast integration**: Sending events into Orb requires no tedious setup steps or explicit field schema for your event
shape, making it instant to start streaming in usage in real-time.


## Event shape

Events are the starting point for all usage calculations in the system, and are simple at their core:

```ts
{
  // customer_id and external_customer_id are used to
  // attribute usage to a given Customer. Exactly one of these
  // should be specified in a given ingestion event.

  // `customer_id` is the Orb generated identifier for the Customer,
  // which is returned from the Create customer API call.
  customer_id: string,

  // external_customer_id is an alternate identifier which is associated
  // with a Customer at creation time. This is treated as an alias for
  // customer_id, and is usually set to an identifier native to your system.
  external_customer_id: string,

  // A string name identifying the event, usually a usage
  // action. By convention, this should not contain any whitespace.
  event_name: string,

  // An ISO 8601 format date with no timezone offset.
  // This should represent the time that usage occurred
  // and is important to attribute usage to a given
  // billing period. See the notes below on determining the timestamp.
  // e.g. 2020-12-09T16:09:53Z
  timestamp: string,

  // A unique value, generated by the client, that is
  // used to de-duplicate events.
  // Exactly one event with a given
  // idempotency key will be ingested, which allows for
  // safe request retries.
  idempotency_key: string

  // Optional custom metadata to attach to the event.
  // This might include a numeric value used for aggregation,
  // or a string/boolean value used for filtering.
  // The schema of this dictionary need not be pre-declared, and
  // properties can be added at any time.
  properties: {
    [key: string]?: string | number | boolean,
  },
}
```

## Required fields
Because events streamed to Orb are meant to be as flexible as possible, there are only a few required fields in every
event.

- We recommend that `idempotency_key` are unique strings that you generated with V4 UUIDs, but only require that they
uniquely identify an event (i.e. don’t collide).
- The `timestamp` field in the event body will be used to determine which billable period a given event falls into. For
example, with a monthly billing cycle starting from the first of December, Orb will calculate metrics based on events
that fall into the range `12-01 00:00:00 <= timestamp < 01-01 00:00:00`.

## Logging metadata

Orb allows tagging events with metadata using a flexible properties dictionary. Since Orb does not enforce a rigid
schema for this field-set, key-value pairs can be added dynamically as your events evolve.

This dictionary can be helpful for a wide variety of use cases:

- Numeric properties on events like `compute_time_ms` can later be inputs to our flexible query engine to determine
usage.
- Logging a region or cluster with each event can help you provide customers more granular visibility into their usage.
- If you are using matrix pricing and matching a matrix price key with a property,
you should ensure the value for that property is sent as a string.

We encourage logging this metadata with an eye towards future use cases to ensure full coverage for historical data. The
datatype of the value in the properties dictionary is important for metric creation from an event source. Values that
you wish to numerically aggregate should be of numeric type in the event.


## Determining event timestamp
For cases where usage is being reported in real time as it is occurring, timestamp should correspond to the time that
usage occurred.

In cases where usage is reported in aggregate for a historical timeframe at a regular interval, we recommend setting the
event `timestamp` to the midpoint of the interval. As an example, if you have an hourly reporter that sends data once an
hour for the previous hour of usage, setting the `timestamp` to the half-hour mark will ensure that the usage is counted
within the correct period.

Note that other time-related fields (e.g. time elapsed) can be added to the properties dictionary as necessary.

In cases where usage is reported in aggregate for a historical timeframe, the timestamp must be within the grace period
set for your account. Events with `timestamp < current_time - grace_period` will not be accepted as a valid event, and
will throw validation errors. Enforcing the grace period enables Orb to accurately map usage to the correct billing
cycle and ensure that all usage is billed for in the corresponding billing period.

In general, Orb does not expect events with future dated timestamps. In cases where the timestamp is at least 24 hours ahead
of the current time, the event will not be accepted as a valid event, and will throw validation errors.

## Event validation

Orb’s validation ensures that you recognize errors in your events as quickly as possible, and the API provides
informative error messages to help you fix problems quickly.

We validate the following:

- Exactly one of `customer_id` and `external_customer_id` should be specified.
- If the `customer_id` is specified, the customer in Orb must exist.
- If the `external_customer_id` is specified, the customer in Orb does not need to exist. Events will be attributed to any
future customers with the `external_customer_id` on subscription creation.
- `timestamp` must conform to ISO 8601 and represent a timestamp at most 1 hour in the future. This timestamp should be
sent in UTC timezone (no timezone offset).

## Idempotency and retry semantics

Orb's idempotency guarantees allow you to implement safe retry logic in the event of network or machine failures,
ensuring data fidelity. Each event in the request payload is associated with an idempotency key, and Orb guarantees that
a single idempotency key will be successfully ingested at most once. Note that when Orb encounters events with duplicate
idempotency keys and differing event bodies in a batch of events, the entire batch will be rejected.

- Successful responses return a 200 HTTP status code. The response contains information about previously processed
events.
- Requests that return a `4xx` HTTP status code indicate a payload error and contain at least one event with a
validation failure. An event with a validation failure can be re-sent to the ingestion endpoint (after the payload is
fixed) with the original idempotency key since that key is not marked as processed.
- Requests that return a `5xx` HTTP status code indicate a server-side failure. These requests should be retried in
their entirety.


## API usage and limits
The ingestion API is designed made for real-time streaming ingestion and architected for high throughput. Even if events
are later deemed unnecessary or filtered out, we encourage you to log them to Orb if they may be relevant to billing
calculations in the future.

To take advantage of the real-time features of the Orb platform and avoid any chance of dropped events by producers, we
recommend reporting events to Orb frequently. Optionally, events can also be briefly aggregated at the source, as this
API accepts an array of event bodies.

Orb does not currently enforce a hard rate-limit for API usage or a maximum request payload size, but please give us a
heads up if you’re changing either of these factors by an order of magnitude from initial setup.

## Testing in debug mode
The ingestion API supports a debug mode, which returns additional verbose output to indicate which event idempotency
keys were newly ingested or duplicates from previous requests. To enable this mode, mark `debug=true` as a query
parameter.

If `debug=true` is not specified, the response will only contain `validation_failed`. Orb will still honor the
idempotency guarantees set [here](/events-and-metrics/event-ingestion#event-volume-and-concurrency) in all
cases.

We strongly recommend that you only use debug mode as part of testing your initial Orb integration. Once you're ready to
switch to production, disable debug mode to take advantage of improved performance and maximal throughput.

#### Example: ingestion response with `debug=true`

```json
{
  "debug": {
    "duplicate": [],
    "ingested": [
      "B7E83HDMfJPAunXW",
      "SJs5DQJ3TnwSqEZE",
      "8SivfDsNKwCeAXim"
    ]
  },
  "validation_failed": []
}
```

#### Example: ingestion response with `debug=false`

```json
{
  "validation_failed": []
}
```

This creates a one-off fixed fee invoice line item on an Invoice.
This can only be done for invoices that are in a `draft` status.

Create invoice line item

This endpoint returns a list of all [`Invoice`](/core-concepts#invoice)s for an account in a list format.

The list of invoices is ordered starting from the most recently issued invoice date. The response also includes
[`pagination_metadata`](/api-reference/pagination), which lets the caller retrieve the next page of results if they
exist.

By default, this only returns invoices that are `issued`, `paid`, or `synced`.

When fetching any `draft` invoices, this returns the last-computed invoice values for each draft invoice, which may
not always be up-to-date since Orb regularly refreshes invoices asynchronously.

List invoices

This endpoint is used to create a one-off invoice for a customer.

Create a one-off invoice

This endpoint can be used to fetch the upcoming [invoice](/core-concepts#invoice) for the current billing
period given a subscription.

Fetch upcoming invoice

This endpoint is used to fetch an [`Invoice`](/core-concepts#invoice) given an identifier.

Fetch invoice

This endpoint allows you to update the `metadata` property on an invoice. If you pass null for the metadata value,
it will clear any existing metadata for that invoice.

`metadata` can be modified regardless of invoice state.

Update invoice

This endpoint allows an eligible invoice to be issued manually. This is only possible with invoices where status is `draft`,
`will_auto_issue` is false, and an `eligible_to_issue_at` is a time in the past. Issuing an invoice could possibly trigger
side effects, some of which could be customer-visible (e.g. sending emails, auto-collecting payment,
syncing the invoice to external providers, etc).

Issue invoice

This endpoint allows an invoice's status to be set the `paid` status. This can only be done to invoices that are in
the `issued` status.

Mark invoice as paid

This endpoint collects payment for an invoice using the customer's default payment method. This action can only be taken on
invoices with status "issued".

Pay invoice

This endpoint allows an invoice's status to be set the `void` status. This can only be done to invoices that are in
the `issued` status.

If the associated invoice has used the customer balance to change the amount due, the customer balance operation
will be reverted. For example, if the invoice used $10 of customer balance, that amount will be added back to the
customer balance upon voiding.

If the invoice was used to purchase a credit block, but the invoice is not yet paid, the credit block will be voided. If the
invoice was created due to a top-up, the top-up will be disabled.

Void invoice

This endpoint returns a list of all Items, ordered in descending order by creation time.

List items

This endpoint is used to create an [Item](/core-concepts#item).

Create item

This endpoint returns an item identified by its item_id.

Fetch item

This endpoint can be used to update properties on the Item.

Update item

This endpoint is used to fetch [metric](/core-concepts##metric) details given a metric identifier.
It returns information about the metrics including its name, description, and item.

List metrics

This endpoint is used to create a [metric](/core-concepts###metric) using a SQL string.
See [SQL support](/extensibility/advanced-metrics#sql-support)
for a description of constructing SQL queries with examples.

Create metric

This endpoint is used to list [metrics](/core-concepts#metric).
It returns information about the metrics including its name, description, and item.

Get metric

This endpoint allows you to update the `metadata` property on a metric. If you pass `null` for the metadata value,
it will clear any existing metadata for that invoice.

Update metric

This endpoint allows you to test your connection to the Orb API and check the validity of your API key, passed in
the Authorization header. This is particularly useful for checking that your environment is set up properly, and is
a great choice for connectors and integrations.

This API does not have any side-effects or return any Orb resources.

Check availability

This endpoint returns a list of all [plans](/core-concepts#plan-and-price) for an account in a list format.
The list of plans is ordered starting from the most recently created plan.
The response also includes [`pagination_metadata`](/api-reference/pagination),
which lets the caller retrieve the next page of results if they exist.

List plans

This endpoint allows creation of plans including their prices.

Create plan

This endpoint is used to fetch [plan](/core-concepts##plan-and-price) details given an external_plan_id
identifier. It returns information about the prices included in the plan and their configuration, as well as
the product that the plan is attached to.

If multiple plans are found to contain the specified external_plan_id, the active plans will take priority over
archived ones, and among those, the endpoint will return the most recently created plan.

## Serialized prices
Orb supports a few different pricing models
out of the box. Each of these models is serialized differently in a given [Price](/core-concepts#plan-and-price)
object. The `model_type` field determines the key for the configuration object that is present. A detailed explanation
of price types can be found in the [Price schema](/core-concepts#plan-and-price). "

Get started

Essentials

Events and metrics

Subscription management

Usage alerting

Invoicing

Data exports

Extending Orb

Overview

Architecture principles

Integrating with Orb

Get started

Essentials

Events and metrics

Subscription management

Usage alerting

Invoicing

Data exports

Extending Orb

​Architecture principles

​Integrating with Orb

Architecture principles

Integrating with Orb