# Orb

## Docs

- [Create customer alert](https://docs.withorb.com/api-reference/alert/create-customer-alert.md): 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 bala…
- [Create customer alert by external ID](https://docs.withorb.com/api-reference/alert/create-customer-alert-by-external-id.md): 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 bala…
- [Create subscription alert](https://docs.withorb.com/api-reference/alert/create-subscription-alert.md): This endpoint is used to create alerts at the subscription level.
- [Disable alert by ID](https://docs.withorb.com/api-reference/alert/disable-alert-by-id.md): 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.
- [Enable alert by ID](https://docs.withorb.com/api-reference/alert/enable-alert-by-id.md): 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.
- [Fetch alert](https://docs.withorb.com/api-reference/alert/fetch-alert.md): This endpoint retrieves an alert by its ID.
- [List alerts](https://docs.withorb.com/api-reference/alert/list-alerts.md): This endpoint returns a list of alerts within Orb.
- [Update alert](https://docs.withorb.com/api-reference/alert/update-alert.md): This endpoint updates the thresholds of an alert.
- [Check availability](https://docs.withorb.com/api-reference/availability/check-availability.md): 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.
- [Cached usage responses](https://docs.withorb.com/api-reference/cached-responses.md)
- [Archive coupon](https://docs.withorb.com/api-reference/coupon/archive-coupon.md): 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.
- [Create coupon](https://docs.withorb.com/api-reference/coupon/create-coupon.md): This endpoint allows the creation of coupons, which can then be redeemed at subscription creation or plan change.
- [Fetch coupon](https://docs.withorb.com/api-reference/coupon/fetch-coupon.md): 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.
- [List coupon subscriptions](https://docs.withorb.com/api-reference/coupon/list-coupon-subscriptions.md): 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 coupons](https://docs.withorb.com/api-reference/coupon/list-coupons.md): This endpoint returns a list of all coupons for an account in a list format.
- [Create credit note](https://docs.withorb.com/api-reference/credit-note/create-credit-note.md): This endpoint is used to create a single [`Credit Note`](/invoicing/credit-notes).
- [Fetch credit note](https://docs.withorb.com/api-reference/credit-note/fetch-credit-note.md): This endpoint is used to fetch a single [`Credit Note`](/invoicing/credit-notes) given an identifier.
- [List credit notes](https://docs.withorb.com/api-reference/credit-note/list-credit-notes.md): 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`.
- [Create ledger entry](https://docs.withorb.com/api-reference/credit/create-ledger-entry.md): 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.
- [Create ledger entry by external ID](https://docs.withorb.com/api-reference/credit/create-ledger-entry-by-external-id.md): 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.
- [Create top-up](https://docs.withorb.com/api-reference/credit/create-top-up.md): 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.
- [Create top-up by external ID](https://docs.withorb.com/api-reference/credit/create-top-up-by-external-id.md): 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.
- [Deactivate top-up](https://docs.withorb.com/api-reference/credit/deactivate-top-up.md): 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](https://docs.withorb.com/api-reference/credit/deactivate-top-up-by-external-id.md): This deactivates the top-up and voids any invoices associated with pending credit blocks purchased through the top-up.
- [Delete credit block](https://docs.withorb.com/api-reference/credit/delete-credit-block.md): This endpoint deletes a credit block by its ID.
- [Fetch credit block](https://docs.withorb.com/api-reference/credit/fetch-credit-block.md): This endpoint returns a credit block identified by its block_id.
- [Fetch customer credit balance](https://docs.withorb.com/api-reference/credit/fetch-customer-credit-balance.md): Returns a paginated list of unexpired, non-zero credit blocks for a customer.
- [Fetch customer credit balance by external customer id](https://docs.withorb.com/api-reference/credit/fetch-customer-credit-balance-by-external-customer-id.md): Returns a paginated list of unexpired, non-zero credit blocks for a customer.
- [Fetch customer credits ledger](https://docs.withorb.com/api-reference/credit/fetch-customer-credits-ledger.md): 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.
- [Fetch customer credits ledger by external ID](https://docs.withorb.com/api-reference/credit/fetch-customer-credits-ledger-by-external-id.md): 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.
- [List invoices for credit block](https://docs.withorb.com/api-reference/credit/list-invoices-for-credit-block.md): This endpoint returns the credit block and its associated purchasing invoices.
- [List top-ups](https://docs.withorb.com/api-reference/credit/list-top-ups.md)
- [List top-ups by external ID](https://docs.withorb.com/api-reference/credit/list-top-ups-by-external-id.md)
- [Create customer](https://docs.withorb.com/api-reference/customer/create-customer.md): 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.
- [Create customer balance transaction](https://docs.withorb.com/api-reference/customer/create-customer-balance-transaction.md): Creates an immutable balance transaction that updates the customer's balance and returns back the newly created transaction.
- [Create portal session](https://docs.withorb.com/api-reference/customer/create-portal-session.md): Creates a portal session for the customer, returning a short-lived URL that provides authenticated access to the customer's billing portal. The session expires after `expires_in_minutes` (default 60, max 180). Creating a new session invalidates any previously active session for that customer.
- [Create portal session by external ID](https://docs.withorb.com/api-reference/customer/create-portal-session-by-external-id.md): Creates a portal session for the customer, returning a short-lived URL that provides authenticated access to the customer's billing portal. The session expires after `expires_in_minutes` (default 60, max 180). Creating a new session invalidates any previously active session for that customer.
- [Delete customer](https://docs.withorb.com/api-reference/customer/delete-customer.md): 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 th…
- [Fetch customer](https://docs.withorb.com/api-reference/customer/fetch-customer.md): 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.
- [Fetch customer by external ID](https://docs.withorb.com/api-reference/customer/fetch-customer-by-external-id.md): This endpoint is used to fetch customer details given an `external_customer_id` (see [Customer ID Aliases](/events-and-metrics/customer-aliases)).
- [Fetch customer costs](https://docs.withorb.com/api-reference/customer/fetch-customer-costs.md): 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 c…
- [Fetch customer costs by external ID](https://docs.withorb.com/api-reference/customer/fetch-customer-costs-by-external-id.md): 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 c…
- [List balance transactions](https://docs.withorb.com/api-reference/customer/list-balance-transactions.md): ## The customer balance
- [List customers](https://docs.withorb.com/api-reference/customer/list-customers.md): 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).
- [Update customer](https://docs.withorb.com/api-reference/customer/update-customer.md): 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`, `additional_emails`, and `currency` of an existing customer. `currency` can only be set if it has not…
- [Update customer by external ID](https://docs.withorb.com/api-reference/customer/update-customer-by-external-id.md): 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 payment methods from payment provider](https://docs.withorb.com/api-reference/customer/update-payment-methods-from-payment-provider.md): Sync Orb's payment methods for the customer with their gateway.
- [Update payment methods from payment provider](https://docs.withorb.com/api-reference/customer/update-payment-methods-from-payment-provider-1.md): Sync Orb's payment methods for the customer with their gateway.
- [Create dimensional price group](https://docs.withorb.com/api-reference/dimensional-price-group/create-dimensional-price-group.md): 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 partition used to derive their usage.
- [Fetch dimensional price group](https://docs.withorb.com/api-reference/dimensional-price-group/fetch-dimensional-price-group.md)
- [Fetch dimensional price group by external ID](https://docs.withorb.com/api-reference/dimensional-price-group/fetch-dimensional-price-group-by-external-id.md)
- [List dimensional price groups](https://docs.withorb.com/api-reference/dimensional-price-group/list-dimensional-price-groups.md)
- [Update dimensional price group](https://docs.withorb.com/api-reference/dimensional-price-group/update-dimensional-price-group.md): This endpoint can be used to update the `external_dimensional_price_group_id` and `metadata` of an existing dimensional price group. Other fields on a dimensional price group are currently immutable.
- [Update dimensional price group by external ID](https://docs.withorb.com/api-reference/dimensional-price-group/update-dimensional-price-group-by-external-id.md): This endpoint can be used to update the `external_dimensional_price_group_id` and `metadata` of an existing dimensional price group. Other fields on a dimensional price group are currently immutable.
- [Error responses](https://docs.withorb.com/api-reference/error-responses.md)
- [Amend event](https://docs.withorb.com/api-reference/event/amend-event.md): 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.
- [Close backfill](https://docs.withorb.com/api-reference/event/close-backfill.md): 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`.
- [Create backfill](https://docs.withorb.com/api-reference/event/create-backfill.md): 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:
- [Deprecate event](https://docs.withorb.com/api-reference/event/deprecate-event.md): 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.
- [Fetch backfill](https://docs.withorb.com/api-reference/event/fetch-backfill.md): This endpoint is used to fetch a backfill given an identifier.
- [Get event volume](https://docs.withorb.com/api-reference/event/get-event-volume.md): This endpoint returns the event volume for an account in a [paginated list format](/api-reference/pagination).
- [Ingest events](https://docs.withorb.com/api-reference/event/ingest-events.md): Orb's event ingestion model and API is designed around two core principles:
- [List backfills](https://docs.withorb.com/api-reference/event/list-backfills.md): This endpoint returns a list of all backfills in a list format.
- [Revert backfill](https://docs.withorb.com/api-reference/event/revert-backfill.md): 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`.
- [Search events](https://docs.withorb.com/api-reference/event/search-events.md): This endpoint returns a filtered set of events for an account in a [paginated list format](/api-reference/pagination).
- [Request idempotency](https://docs.withorb.com/api-reference/idempotency.md)
- [Create a one-off invoice](https://docs.withorb.com/api-reference/invoice/create-a-one-off-invoice.md): This endpoint is used to create a one-off invoice for a customer.
- [Create invoice line item](https://docs.withorb.com/api-reference/invoice/create-invoice-line-item.md): 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.
- [Delete invoice line item](https://docs.withorb.com/api-reference/invoice/delete-invoice-line-item.md): This endpoint deletes an invoice line item from a draft invoice.
- [Fetch invoice](https://docs.withorb.com/api-reference/invoice/fetch-invoice.md): This endpoint is used to fetch an [`Invoice`](/core-concepts#invoice) given an identifier.
- [Fetch upcoming invoice](https://docs.withorb.com/api-reference/invoice/fetch-upcoming-invoice.md): This endpoint can be used to fetch the upcoming [invoice](/core-concepts#invoice) for the current billing period given a subscription.
- [Issue invoice](https://docs.withorb.com/api-reference/invoice/issue-invoice.md): 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-visibl…
- [Issue invoice summary](https://docs.withorb.com/api-reference/invoice/issue-invoice-summary.md): 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-visibl…
- [List invoices](https://docs.withorb.com/api-reference/invoice/list-invoices.md): This endpoint returns a list of all [`Invoice`](/core-concepts#invoice)s for an account in a list format.
- [List invoices summary](https://docs.withorb.com/api-reference/invoice/list-invoices-summary.md): This is a lighter-weight endpoint that returns a list of all [`Invoice`](/core-concepts#invoice) summaries for an account in a list format.
- [Mark invoice as paid](https://docs.withorb.com/api-reference/invoice/mark-invoice-as-paid.md): This endpoint allows an invoice's status to be set to the `paid` status. This can only be done to invoices that are in the `issued` or `synced` status.
- [Pay invoice](https://docs.withorb.com/api-reference/invoice/pay-invoice.md): This endpoint collects payment for an invoice. By default, it uses the customer's default payment method. Optionally, a shared payment token (SPT) can be provided to pay using agent-granted credentials instead. This action can only be taken on invoices with status "issued".
- [Regenerate invoice PDF](https://docs.withorb.com/api-reference/invoice/regenerate-invoice-pdf.md): This endpoint triggers a regeneration of the PDF for a finalized invoice.
- [Regenerate receipt PDF](https://docs.withorb.com/api-reference/invoice/regenerate-receipt-pdf.md): This endpoint triggers a regeneration of the receipt PDF for a paid invoice.
- [Update invoice](https://docs.withorb.com/api-reference/invoice/update-invoice.md): This endpoint allows you to update the `metadata`, `net_terms`, `due_date`, `invoice_date`, and `auto_collection` properties on an invoice. If you pass null for the metadata value, it will clear any existing metadata for that invoice.
- [Void invoice](https://docs.withorb.com/api-reference/invoice/void-invoice.md): This endpoint allows an invoice's status to be set to the `void` status. This can only be done to invoices that are in the `issued` status.
- [Archive item](https://docs.withorb.com/api-reference/item/archive-item.md)
- [Create item](https://docs.withorb.com/api-reference/item/create-item.md): This endpoint is used to create an [Item](/core-concepts#item).
- [Fetch item](https://docs.withorb.com/api-reference/item/fetch-item.md): This endpoint returns an item identified by its item_id.
- [List items](https://docs.withorb.com/api-reference/item/list-items.md): This endpoint returns a list of all Items, ordered in descending order by creation time.
- [Update item](https://docs.withorb.com/api-reference/item/update-item.md): This endpoint can be used to update properties on the Item.
- [Create a new license for a user](https://docs.withorb.com/api-reference/license/create-a-new-license-for-a-user.md): This endpoint is used to create a new license for a user.
- [Deactivate license](https://docs.withorb.com/api-reference/license/deactivate-license.md): This endpoint is used to deactivate an existing license.
- [Fetch license](https://docs.withorb.com/api-reference/license/fetch-license.md): This endpoint is used to fetch a license given an identifier.
- [Fetch license by external license id](https://docs.withorb.com/api-reference/license/fetch-license-by-external-license-id.md): This endpoint is used to fetch a license given an external license identifier.
- [Get usage for a license by external license ID](https://docs.withorb.com/api-reference/license/get-usage-for-a-license-by-external-license-id.md): Returns usage and remaining credits for a license identified by its external license ID.
- [Get usage for a specific license](https://docs.withorb.com/api-reference/license/get-usage-for-a-specific-license.md): Returns usage and remaining credits for a specific license over a date range.
- [Get usage for all licenses of a type on a subscription](https://docs.withorb.com/api-reference/license/get-usage-for-all-licenses-of-a-type-on-a-subscription.md): Returns usage and remaining credits for all licenses of a given type on a subscription.
- [List licenses](https://docs.withorb.com/api-reference/license/list-licenses.md): This endpoint returns a list of all licenses for a subscription.
- [Create license type](https://docs.withorb.com/api-reference/licensetype/create-license-type.md): This endpoint is used to create a new license type.
- [Fetch license type](https://docs.withorb.com/api-reference/licensetype/fetch-license-type.md): This endpoint returns a license type identified by its license_type_id.
- [List license types](https://docs.withorb.com/api-reference/licensetype/list-license-types.md): This endpoint returns a list of all license types configured for the account, ordered in ascending order by creation time.
- [Create metric](https://docs.withorb.com/api-reference/metric/create-metric.md): 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.
- [Get metric](https://docs.withorb.com/api-reference/metric/get-metric.md): This endpoint is used to list [metrics](/core-concepts#metric). It returns information about the metrics including its name, description, and item.
- [List metrics](https://docs.withorb.com/api-reference/metric/list-metrics.md): 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.
- [Update metric](https://docs.withorb.com/api-reference/metric/update-metric.md): 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.
- [Pagination](https://docs.withorb.com/api-reference/pagination.md)
- [Cancel migration](https://docs.withorb.com/api-reference/plan/cancel-migration.md): This endpoint cancels a migration.
- [Create plan](https://docs.withorb.com/api-reference/plan/create-plan.md): This endpoint allows creation of plans including their prices.
- [Create plan version](https://docs.withorb.com/api-reference/plan/create-plan-version.md): This endpoint allows the creation of a new plan version for an existing plan.
- [Create plan version by external ID](https://docs.withorb.com/api-reference/plan/create-plan-version-by-external-id.md): This endpoint allows the creation of a new plan version for an existing plan.
- [Fetch migration](https://docs.withorb.com/api-reference/plan/fetch-migration.md)
- [Fetch plan](https://docs.withorb.com/api-reference/plan/fetch-plan.md): This endpoint is used to fetch [plan](/core-concepts#plan-and-price) details given a plan 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.
- [Fetch plan by external ID](https://docs.withorb.com/api-reference/plan/fetch-plan-by-external-id.md): 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.
- [Fetch plan version](https://docs.withorb.com/api-reference/plan/fetch-plan-version.md): This endpoint is used to fetch a plan version. It returns the phases, prices, and adjustments present on this version of the plan.
- [Fetch plan version by external ID](https://docs.withorb.com/api-reference/plan/fetch-plan-version-by-external-id.md): This endpoint is used to fetch a plan version. It returns the phases, prices, and adjustments present on this version of the plan.
- [List migrations](https://docs.withorb.com/api-reference/plan/list-migrations.md): This endpoint returns a list of all migrations for a plan. The list of migrations is ordered starting from the most recently created migration. The response also includes pagination_metadata, which lets the caller retrieve the next page of results if they exist.
- [List plans](https://docs.withorb.com/api-reference/plan/list-plans.md): 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 nex…
- [Set plan version as default](https://docs.withorb.com/api-reference/plan/set-plan-version-as-default.md): This endpoint allows setting the default version of a plan.
- [Set plan version as default by external ID](https://docs.withorb.com/api-reference/plan/set-plan-version-as-default-by-external-id.md): This endpoint allows setting the default version of a plan.
- [Update plan by external ID](https://docs.withorb.com/api-reference/plan/update-plan-by-external-id.md): This endpoint can be used to update the `external_plan_id`, `description`, and `metadata` of an existing plan.
- [Update plan by id](https://docs.withorb.com/api-reference/plan/update-plan-by-id.md): This endpoint can be used to update the `external_plan_id`, `description`, and `metadata` of an existing plan.
- [Add or edit price intervals](https://docs.withorb.com/api-reference/price-interval/add-or-edit-price-intervals.md): This endpoint is used to add and edit subscription [price intervals](/api-reference/price-interval/add-or-edit-price-intervals). By making modifications to a subscription’s price intervals, you can [flexibly and atomically control the billing behavior of a subscription](/product-catalog/modifying-su…
- [Create price](https://docs.withorb.com/api-reference/price/create-price.md): This endpoint is used to create a [price](/product-catalog/price-configuration). A price created using this endpoint is always an add-on, meaning that it's not associated with a specific plan and can instead be individually added to subscriptions, including subscriptions on different plans.
- [Evaluate multiple prices](https://docs.withorb.com/api-reference/price/evaluate-multiple-prices.md): This endpoint is used to evaluate the output of price(s) for a given customer and time range over ingested events. It enables filtering and grouping the output using [computed properties](/extensibility/advanced-metrics#computed-properties), supporting the following workflows:
- [Evaluate preview events](https://docs.withorb.com/api-reference/price/evaluate-preview-events.md): This endpoint evaluates prices on preview events instead of actual usage, making it ideal for building price calculators and cost estimation tools. You can filter and group results using [computed properties](/extensibility/advanced-metrics#computed-properties) to analyze pricing across different di…
- [Evaluate price](https://docs.withorb.com/api-reference/price/evaluate-price.md): [NOTE] It is recommended to use the `/v1/prices/evaluate` which offers further functionality, such as multiple prices, inline price definitions, and querying over preview events.
- [Fetch price](https://docs.withorb.com/api-reference/price/fetch-price.md): This endpoint returns a price given an identifier.
- [Fetch price by external price id](https://docs.withorb.com/api-reference/price/fetch-price-by-external-price-id.md): This endpoint returns a price given an external price id. See the [price creation API](/api-reference/price/create-price) for more information about external price aliases.
- [List prices](https://docs.withorb.com/api-reference/price/list-prices.md): This endpoint is used to list all add-on prices created using the [price creation endpoint](/api-reference/price/create-price).
- [Update price](https://docs.withorb.com/api-reference/price/update-price.md): This endpoint allows you to update the `metadata` property on a price. If you pass null for the metadata value, it will clear any existing metadata for that price.
- [Update price by external price id](https://docs.withorb.com/api-reference/price/update-price-by-external-price-id.md): This endpoint allows you to update the `metadata` property on a price. If you pass null for the metadata value, it will clear any existing metadata for that price.
- [Rate limits](https://docs.withorb.com/api-reference/rate-limits.md)
- [Reliability and scaling](https://docs.withorb.com/api-reference/reliability.md)
- [Apply subscription change](https://docs.withorb.com/api-reference/subscription-change/apply-subscription-change.md): Apply a subscription change to perform the intended action. If a positive amount is passed with a request to this endpoint, any eligible invoices that were created will be issued immediately if they only contain in-advance fees.
- [Cancel subscription change](https://docs.withorb.com/api-reference/subscription-change/cancel-subscription-change.md): Cancel a subscription change. The change can no longer be applied. A subscription can only have one "pending" change at a time - use this endpoint to cancel an existing change before creating a new one.
- [Fetch subscription change](https://docs.withorb.com/api-reference/subscription-change/fetch-subscription-change.md): This endpoint returns a subscription change given an identifier.
- [List subscription changes](https://docs.withorb.com/api-reference/subscription-change/list-subscription-changes.md): This endpoint returns a list of pending subscription changes for a customer. Use the [Fetch Subscription Change](fetch-subscription-change) endpoint to retrieve the expected subscription state after the pending change is applied.
- [Cancel subscription](https://docs.withorb.com/api-reference/subscription/cancel-subscription.md): This endpoint can be used to cancel an existing subscription. It returns the serialized subscription object with an `end_date` parameter that signifies when the subscription will transition to an ended state.
- [Create subscription](https://docs.withorb.com/api-reference/subscription/create-subscription.md): A subscription represents the purchase of a plan by a customer. The customer is identified by either the `customer_id` or the `external_customer_id`, and exactly one of these fields must be provided.
- [Fetch subscription](https://docs.withorb.com/api-reference/subscription/fetch-subscription.md): This endpoint is used to fetch a [Subscription](/core-concepts##subscription) given an identifier.
- [Fetch subscription costs](https://docs.withorb.com/api-reference/subscription/fetch-subscription-costs.md): This endpoint is used to fetch a day-by-day snapshot of a subscription's costs in Orb, calculated by applying pricing information to the underlying usage (see the [subscription usage endpoint](fetch-subscription-usage) to fetch usage per metric, in usage units rather than a currency).
- [Fetch subscription schedule](https://docs.withorb.com/api-reference/subscription/fetch-subscription-schedule.md): This endpoint returns a [paginated](/api-reference/pagination) list of all plans associated with a subscription along with their start and end dates. This list contains the subscription's initial plan along with past and future plan changes.
- [Fetch subscription usage](https://docs.withorb.com/api-reference/subscription/fetch-subscription-usage.md): This endpoint is used to fetch a subscription's usage in Orb. Especially when combined with optional query parameters, this endpoint is a powerful way to build visualizations on top of Orb's event data and metrics.
- [List subscriptions](https://docs.withorb.com/api-reference/subscription/list-subscriptions.md): This endpoint returns a list of all subscriptions for an account 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).
- [Redeem Coupon](https://docs.withorb.com/api-reference/subscription/redeem-coupon.md): Redeem a coupon effective at a given time.
- [Schedule plan change](https://docs.withorb.com/api-reference/subscription/schedule-plan-change.md): This endpoint can be used to change an existing subscription's plan. It returns the serialized updated subscription object.
- [Trigger phase](https://docs.withorb.com/api-reference/subscription/trigger-phase.md): Manually trigger a phase, effective the given date (or the current time, if not specified).
- [Unschedule fixed fee quantity updates](https://docs.withorb.com/api-reference/subscription/unschedule-fixed-fee-quantity-updates.md): This endpoint can be used to clear scheduled updates to the quantity for a fixed fee.
- [Unschedule plan change](https://docs.withorb.com/api-reference/subscription/unschedule-plan-change.md): This endpoint can be used to unschedule any pending plan changes on an existing subscription. When called, all upcoming plan changes will be unscheduled.
- [Unschedule subscription cancellation](https://docs.withorb.com/api-reference/subscription/unschedule-subscription-cancellation.md): This endpoint can be used to unschedule any pending cancellations for a subscription.
- [Update price quantity](https://docs.withorb.com/api-reference/subscription/update-price-quantity.md): This endpoint can be used to update the quantity for a fixed fee.
- [Update subscription](https://docs.withorb.com/api-reference/subscription/update-subscription.md): This endpoint can be used to update the `metadata`, `net terms`, `auto_collection`, `invoicing_threshold`, and `default_invoice_memo` properties on a subscription.
- [Update trial for subscription](https://docs.withorb.com/api-reference/subscription/update-trial-for-subscription.md): This endpoint is used to update the trial end date for a subscription. The new trial end date must be within the time range of the current plan (i.e. the new trial end date must be on or after the subscription's start date on the current plan, and on or before the subscription end date).
- [Diff-based engine](https://docs.withorb.com/architecture/billing-architecture.md)
- [Query-based billing](https://docs.withorb.com/architecture/query-based-billing.md)
- [Core concepts](https://docs.withorb.com/core-concepts.md)
- [Athena](https://docs.withorb.com/data-exports/athena.md)
- [Aurora mysql](https://docs.withorb.com/data-exports/aurora-mysql.md)
- [Aurora postgres](https://docs.withorb.com/data-exports/aurora-postgres.md)
- [Best practices](https://docs.withorb.com/data-exports/best-practices.md)
- [Big query](https://docs.withorb.com/data-exports/big-query.md)
- [Databricks](https://docs.withorb.com/data-exports/databricks.md)
- [Data Exports Overview](https://docs.withorb.com/data-exports/introduction.md)
- [Motherduck](https://docs.withorb.com/data-exports/motherduck.md)
- [Postgres](https://docs.withorb.com/data-exports/postgres.md)
- [Redshift](https://docs.withorb.com/data-exports/redshift.md)
- [Exported resource types](https://docs.withorb.com/data-exports/resource-types.md)
- [S3](https://docs.withorb.com/data-exports/s3.md)
- [Snowflake](https://docs.withorb.com/data-exports/snowflake.md)
- [Snowflake password deprecation](https://docs.withorb.com/data-exports/snowflake-password-deprecation.md)
- [Financial analyses using Orb data](https://docs.withorb.com/data-exports/use-cases.md)
- [Enterprise billing with Orb](https://docs.withorb.com/enterprise/enterprise-billing.md)
- [Managing enterprise credits](https://docs.withorb.com/enterprise/managing-credits.md)
- [Audit logs](https://docs.withorb.com/essentials/audit-logs.md)
- [Authentication](https://docs.withorb.com/essentials/authentication.md)
- [Dry run requests](https://docs.withorb.com/essentials/dry-run.md)
- [Pending changes](https://docs.withorb.com/essentials/pending-changes.md)
- [Postman](https://docs.withorb.com/essentials/postman.md)
- [Preview side effects](https://docs.withorb.com/essentials/previews.md)
- [Production readiness review](https://docs.withorb.com/essentials/production-readiness-review.md)
- [SDK](https://docs.withorb.com/essentials/sdk.md)
- [Timezone localization](https://docs.withorb.com/essentials/timezones.md)
- [Integrate with cloud storage](https://docs.withorb.com/events-and-metrics/cloud-storage-integration.md)
- [Construct metrics](https://docs.withorb.com/events-and-metrics/construct-metrics.md)
- [Customer aliases](https://docs.withorb.com/events-and-metrics/customer-aliases.md)
- [Ingest events](https://docs.withorb.com/events-and-metrics/event-ingestion.md)
- [Hosted rollups](https://docs.withorb.com/events-and-metrics/high-throughput-ingestion.md)
- [Parameterized metrics](https://docs.withorb.com/events-and-metrics/parameterized-metrics.md)
- [Events query explorer](https://docs.withorb.com/events-and-metrics/query-explorer.md)
- [Querying data with SQL](https://docs.withorb.com/events-and-metrics/querying-with-sql.md)
- [Backfill and amend events](https://docs.withorb.com/events-and-metrics/reporting-errors.md)
- [Segment integration](https://docs.withorb.com/events-and-metrics/segment-integration.md)
- [Advanced metrics](https://docs.withorb.com/extensibility/advanced-metrics.md)
- [Custom pricing](https://docs.withorb.com/extensibility/custom-pricing.md)
- [AR aging](https://docs.withorb.com/financial-operations/ar-aging.md)
- [Essential dunning](https://docs.withorb.com/financial-operations/essential-dunning.md)
- [How Orb works](https://docs.withorb.com/how-orb-works.md): The building blocks of usage-based billing
- [Bill.com](https://docs.withorb.com/integrations-and-exports/billcom.md)
- [Cloud marketplaces](https://docs.withorb.com/integrations-and-exports/cloud-marketplaces.md)
- [Overview](https://docs.withorb.com/integrations-and-exports/introduction.md)
- [NetSuite](https://docs.withorb.com/integrations-and-exports/netsuite.md)
- [QuickBooks](https://docs.withorb.com/integrations-and-exports/quickbooks.md)
- [Overview](https://docs.withorb.com/integrations-and-exports/salesforce/index.md)
- [Provision in Orb from Salesforce](https://docs.withorb.com/integrations-and-exports/salesforce/salesforce-cpq.md)
- [Sync Orb data to Salesforce](https://docs.withorb.com/integrations-and-exports/salesforce/salesforce-crm.md)
- [Schema](https://docs.withorb.com/integrations-and-exports/salesforce/schema.md)
- [Overview](https://docs.withorb.com/integrations-and-exports/stripe.md)
- [India e-Mandates](https://docs.withorb.com/integrations-and-exports/stripe-india-mandates.md): Set up and test India e-Mandates with Stripe for recurring payment collection
- [Shared Payment Tokens](https://docs.withorb.com/integrations-and-exports/stripe-shared-payment-tokens.md): Use Stripe Shared Payment Tokens (SPTs) for agent-facilitated commerce
- [Summary webhooks](https://docs.withorb.com/integrations-and-exports/summary-webhooks.md)
- [Enrich invoices with tax](https://docs.withorb.com/integrations-and-exports/tax.md)
- [Third-party managed integrations](https://docs.withorb.com/integrations-and-exports/third-party-integrations.md): Externally created and maintained wrappers, connectors, and integrations.
- [Webhooks](https://docs.withorb.com/integrations-and-exports/webhooks.md)
- [What is Orb?](https://docs.withorb.com/introduction.md)
- [Adjust draft invoices](https://docs.withorb.com/invoicing/Invoice-adjustments.md)
- [Advanced dunning](https://docs.withorb.com/invoicing/advanced-dunning.md)
- [Credit notes](https://docs.withorb.com/invoicing/credit-notes.md)
- [Customer balance](https://docs.withorb.com/invoicing/customer-balance-transactions.md)
- [Invoicing Overview](https://docs.withorb.com/invoicing/introduction.md)
- [Invoice calculation examples](https://docs.withorb.com/invoicing/invoice-calculation-examples.md)
- [Invoice calculations](https://docs.withorb.com/invoicing/invoice-calculations.md)
- [CSV downloads](https://docs.withorb.com/invoicing/invoice-csv-downloads.md)
- [Invoice delivery](https://docs.withorb.com/invoicing/invoice-delivery.md)
- [Invoice display](https://docs.withorb.com/invoicing/invoice-display.md)
- [Invoice issuance](https://docs.withorb.com/invoicing/invoice-issuance.md): Orb's invoice issuance system controls when and how invoices transition from draft to issued status. This guide covers configuration options and issuance behavior for different invoice types.
- [Invoice portal](https://docs.withorb.com/invoicing/invoice-portal.md)
- [One-off invoices](https://docs.withorb.com/invoicing/one-off-invoice-creation.md)
- [Payments](https://docs.withorb.com/invoicing/payments.md)
- [Structure and lifecycle](https://docs.withorb.com/invoicing/structure.md)
- [Threshold Invoicing](https://docs.withorb.com/invoicing/threshold-invoicing.md)
- [Migrating from Stripe Billing](https://docs.withorb.com/migration-guides/stripe-billing.md)
- [Next steps](https://docs.withorb.com/next-steps.md)
- [Overview](https://docs.withorb.com/overview.md)
- [Applying adjustments and discounts](https://docs.withorb.com/product-catalog/adjustments.md)
- [Configuring plans](https://docs.withorb.com/product-catalog/build-catalog.md)
- [Creating subscriptions](https://docs.withorb.com/product-catalog/creating-subscriptions.md)
- [Credit systems](https://docs.withorb.com/product-catalog/credit-systems.md)
- [Customer hierarchy](https://docs.withorb.com/product-catalog/customer-hierarchy.md)
- [Dimensional pricing](https://docs.withorb.com/product-catalog/dimensional-pricing.md)
- [Subscription edits](https://docs.withorb.com/product-catalog/editing-subscriptions.md)
- [License alerting](https://docs.withorb.com/product-catalog/license-alerting.md)
- [License allocations](https://docs.withorb.com/product-catalog/license-allocations.md)
- [License configuration](https://docs.withorb.com/product-catalog/license-pricing.md)
- [Configure prepaid credits](https://docs.withorb.com/product-catalog/prepurchase.md)
- [Executing a price change](https://docs.withorb.com/product-catalog/price-changes.md)
- [Price configuration](https://docs.withorb.com/product-catalog/price-configuration.md)
- [Scoped credit blocks](https://docs.withorb.com/product-catalog/scoped-credits.md)
- [Subscription plan changes](https://docs.withorb.com/product-catalog/subscription-plan-change.md)
- [View subscription usage](https://docs.withorb.com/product-catalog/usage-visibility.md)
- [Quickstart overview](https://docs.withorb.com/quickstart-guide.md)
- [Ingest events](https://docs.withorb.com/quickstart/ingest.md)
- [Invoice your customers](https://docs.withorb.com/quickstart/invoicing.md)
- [Create a billable metric](https://docs.withorb.com/quickstart/metrics.md)
- [Configure your pricing](https://docs.withorb.com/quickstart/pricing.md)
- [Manage subscriptions](https://docs.withorb.com/quickstart/subscriptions.md)
- [Month-end close](https://docs.withorb.com/revenue-reporting/month-end-close.md): A step-by-step guide for finance teams to close accounting periods in Orb
- [Reporting configurations](https://docs.withorb.com/revenue-reporting/reporting-pivots.md)
- [Recognition methodology](https://docs.withorb.com/revenue-reporting/revenue-recognition.md)
- [Examples](https://docs.withorb.com/revenue-reporting/revenue-recognition-examples.md)
- [Pricing an AI agent](https://docs.withorb.com/self-serve/agent-pricing.md)
- [Product access with prepaid credits](https://docs.withorb.com/self-serve/product-access.md)
- [Trials with prepaid credits](https://docs.withorb.com/self-serve/trial-management.md)
- [Use case guide: evolve existing pricing](https://docs.withorb.com/simulations/evolve-pricing.md)
- [Use case guide: launching new products](https://docs.withorb.com/simulations/new-product.md)
- [Make your first billable metric](https://docs.withorb.com/tutorials/first-billable-metric.md): Billable metrics are a core feature that allows you to measure the usage events you send to Orb. These metrics power your usage-based pricing by tracking customer interactions and activities. This guide will walk you through creating your first billable metric in Orb and understanding its functions.
- [Use the prepurchase ledger with custom credits](https://docs.withorb.com/tutorials/first-custom-credits.md): The prepurchase credit ledger allows you to allocate a set amount of credits to customers that can be drawn down as they use your service. This system enables you to allocate credits either monthly, one-time, or based on your specific use case. Here's how you can set up and use it.
- [Collect payment against your first issued invoice](https://docs.withorb.com/tutorials/first-payment.md): Once you have created a subscription and issued invoices in Orb, the next step is to charge those invoices. This guide will show you how to set up payment workflows using Stripe Test Mode and simulate the complete payment process with test customers and fake credit cards.
- [Make your first plan](https://docs.withorb.com/tutorials/first-plan.md): In this guide, we’ll walk you through setting up a plan in Orb to help you manage your usage-based pricing. Plans define how you structure your pricing, whether based on usage metrics, fixed pricing, or a combination of both.
- [Make your first subscription](https://docs.withorb.com/tutorials/first-subscription.md): This guide will walk you through creating a customer and subscription in Orb. You’ll learn how to customize settings and subscription details for each customer.
- [Send your first usage event](https://docs.withorb.com/tutorials/first-usage-event.md): This guide will walk you through the steps to send your first usage event into Orb using Postman. Follow along to ensure a smooth experience while experimenting in Orb’s test mode environment.
- [Use the prepurchase ledger with multiple custom credit types](https://docs.withorb.com/tutorials/multiple-custom-credits.md): Orb allows you to define multiple types of custom pricing units to manage various products or services under different credit pools. This feature is useful when you want separate credit allocations for different types of usage, such as API calls and transactions. Here’s how to set up and manage mult…
- [Walk through the Orb settings](https://docs.withorb.com/tutorials/settings.md): This guide walks you through the key settings available in Orb, covering invoicing, email notifications, integrations, and more. Understanding these settings will help you customize your workflows and manage customer interactions efficiently.
- [Balance alerts](https://docs.withorb.com/usage-alerting/balance-alerts.md): Detect when a customer’s prepaid‑credit balance is depleted, drops below a threshold, or recovers.
- [Alerting overview](https://docs.withorb.com/usage-alerting/overview.md): Configure cost, usage, and balance alerts and understand their evaluation SLAs.
- [Spend management](https://docs.withorb.com/usage-alerting/spend-management.md): Use alerts and limits to help customers manage and cap their spend.
- [Subscription alerts](https://docs.withorb.com/usage-alerting/subscription-alerts.md): Configure cost and usage‑based alerts at the plan or individual subscription level.

## OpenAPI Specs

- [orb-openapi](https://docs.withorb.com/api-reference/orb-openapi.json)
- [package](https://docs.withorb.com/open-api-to-postman/package.json)
- [package-lock](https://docs.withorb.com/open-api-to-postman/package-lock.json)
- [_category_](https://docs.withorb.com/integrations-and-exports/_category_.yml)

## Optional

- [Changelog](https://changelog.withorb.com)
- [Status](https://status.withorb.com)
- [Blog](https://www.withorb.com/blog)