# Orb

## Docs

- [Overview](https://docs.withorb.com/overview.md)
- [What is Orb?](https://docs.withorb.com/introduction.md)
- [How Orb works](https://docs.withorb.com/how-orb-works.md): The building blocks of usage-based billing
- [Core concepts](https://docs.withorb.com/core-concepts.md)
- [Quickstart overview](https://docs.withorb.com/quickstart-guide.md)
- [Ingest events](https://docs.withorb.com/quickstart/ingest.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)
- [Invoice your customers](https://docs.withorb.com/quickstart/invoicing.md)
- [Next steps](https://docs.withorb.com/next-steps.md)
- [Query-based billing](https://docs.withorb.com/architecture/query-based-billing.md)
- [Diff-based engine](https://docs.withorb.com/architecture/billing-architecture.md)
- [Authentication](https://docs.withorb.com/essentials/authentication.md)
- [Audit logs](https://docs.withorb.com/essentials/audit-logs.md)
- [SDK](https://docs.withorb.com/essentials/sdk.md)
- [Postman](https://docs.withorb.com/essentials/postman.md)
- [Timezone localization](https://docs.withorb.com/essentials/timezones.md)
- [Production readiness review](https://docs.withorb.com/essentials/production-readiness-review.md)
- [Dry run requests](https://docs.withorb.com/essentials/dry-run.md)
- [Preview side effects](https://docs.withorb.com/essentials/previews.md)
- [Pending changes](https://docs.withorb.com/essentials/pending-changes.md)
- [Ingest events](https://docs.withorb.com/events-and-metrics/event-ingestion.md)
- [Integrate with cloud storage](https://docs.withorb.com/events-and-metrics/cloud-storage-integration.md)
- [Segment integration](https://docs.withorb.com/events-and-metrics/segment-integration.md)
- [Construct metrics](https://docs.withorb.com/events-and-metrics/construct-metrics.md)
- [Parameterized metrics](https://docs.withorb.com/events-and-metrics/parameterized-metrics.md)
- [Customer aliases](https://docs.withorb.com/events-and-metrics/customer-aliases.md)
- [Hosted rollups](https://docs.withorb.com/events-and-metrics/high-throughput-ingestion.md)
- [Querying data with SQL](https://docs.withorb.com/events-and-metrics/querying-with-sql.md)
- [Events query explorer](https://docs.withorb.com/events-and-metrics/query-explorer.md)
- [Backfill and amend events](https://docs.withorb.com/events-and-metrics/reporting-errors.md)
- [Configuring plans](https://docs.withorb.com/product-catalog/build-catalog.md)
- [Price configuration](https://docs.withorb.com/product-catalog/price-configuration.md)
- [License configuration](https://docs.withorb.com/product-catalog/license-pricing.md)
- [License allocations](https://docs.withorb.com/product-catalog/license-allocations.md)
- [License alerting](https://docs.withorb.com/product-catalog/license-alerting.md)
- [Dimensional pricing](https://docs.withorb.com/product-catalog/dimensional-pricing.md)
- [Creating subscriptions](https://docs.withorb.com/product-catalog/creating-subscriptions.md)
- [Subscription edits](https://docs.withorb.com/product-catalog/editing-subscriptions.md)
- [Subscription plan changes](https://docs.withorb.com/product-catalog/subscription-plan-change.md)
- [Applying adjustments and discounts](https://docs.withorb.com/product-catalog/adjustments.md)
- [Configure prepaid credits](https://docs.withorb.com/product-catalog/prepurchase.md)
- [Credit systems](https://docs.withorb.com/product-catalog/credit-systems.md)
- [Scoped credit blocks](https://docs.withorb.com/product-catalog/scoped-credits.md)
- [Executing a price change](https://docs.withorb.com/product-catalog/price-changes.md)
- [View subscription usage](https://docs.withorb.com/product-catalog/usage-visibility.md)
- [Customer hierarchy](https://docs.withorb.com/product-catalog/customer-hierarchy.md)
- [Alerting overview](https://docs.withorb.com/usage-alerting/overview.md): Configure cost, usage, and balance alerts and understand their evaluation SLAs.
- [Subscription alerts](https://docs.withorb.com/usage-alerting/subscription-alerts.md): Configure cost and usage‑based alerts at the plan or individual subscription level.
- [Grouped cost alerts](https://docs.withorb.com/usage-alerting/grouped-cost-alerts.md): Evaluate per‑group spend subtotals (e.g. per seat or tenant) instead of the single subscription invoice total.
- [Spend alerts](https://docs.withorb.com/usage-alerting/spend-alerts.md): Evaluate rated spend—the pricing subtotal before credits and invoice‑level adjustments—instead of the net invoice total.
- [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.
- [Spend management](https://docs.withorb.com/usage-alerting/spend-management.md): Use alerts and limits to help customers manage and cap their spend.
- [Invoicing Overview](https://docs.withorb.com/invoicing/introduction.md)
- [Structure and lifecycle](https://docs.withorb.com/invoicing/structure.md)
- [Invoice calculations](https://docs.withorb.com/invoicing/invoice-calculations.md)
- [Invoice calculation examples](https://docs.withorb.com/invoicing/invoice-calculation-examples.md)
- [Adjust draft invoices](https://docs.withorb.com/invoicing/Invoice-adjustments.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.
- [Payments](https://docs.withorb.com/invoicing/payments.md)
- [Customer balance](https://docs.withorb.com/invoicing/customer-balance-transactions.md)
- [Invoice portal](https://docs.withorb.com/invoicing/invoice-portal.md)
- [Invoice delivery](https://docs.withorb.com/invoicing/invoice-delivery.md)
- [Invoice display](https://docs.withorb.com/invoicing/invoice-display.md)
- [One-off invoices](https://docs.withorb.com/invoicing/one-off-invoice-creation.md)
- [Threshold Invoicing](https://docs.withorb.com/invoicing/threshold-invoicing.md)
- [Cumulative invoicing](https://docs.withorb.com/invoicing/cumulative-invoicing.md)
- [Credit notes](https://docs.withorb.com/invoicing/credit-notes.md)
- [CSV downloads](https://docs.withorb.com/invoicing/invoice-csv-downloads.md)
- [AR aging](https://docs.withorb.com/financial-operations/ar-aging.md)
- [Essential dunning](https://docs.withorb.com/financial-operations/essential-dunning.md)
- [Collections Automations](https://docs.withorb.com/financial-operations/automations.md)
- [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)
- [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
- [Data Exports Overview](https://docs.withorb.com/data-exports/introduction.md)
- [Best practices](https://docs.withorb.com/data-exports/best-practices.md)
- [Financial analyses using Orb data](https://docs.withorb.com/data-exports/use-cases.md)
- [Exported resource types](https://docs.withorb.com/data-exports/resource-types.md)
- [Athena](https://docs.withorb.com/data-exports/athena.md)
- [Aurora postgres](https://docs.withorb.com/data-exports/aurora-postgres.md)
- [Aurora mysql](https://docs.withorb.com/data-exports/aurora-mysql.md)
- [Big query](https://docs.withorb.com/data-exports/big-query.md)
- [Databricks](https://docs.withorb.com/data-exports/databricks.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)
- [Snowflake](https://docs.withorb.com/data-exports/snowflake.md)
- [Snowflake password deprecation](https://docs.withorb.com/data-exports/snowflake-password-deprecation.md)
- [S3](https://docs.withorb.com/data-exports/s3.md)
- [Use case guide: launching new products](https://docs.withorb.com/simulations/new-product.md)
- [Use case guide: evolve existing pricing](https://docs.withorb.com/simulations/evolve-pricing.md)
- [Advanced metrics](https://docs.withorb.com/extensibility/advanced-metrics.md)
- [Custom pricing](https://docs.withorb.com/extensibility/custom-pricing.md)
- [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.
- [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.
- [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.
- [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.
- [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.
- [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.
- [Building a usage dashboard](https://docs.withorb.com/usage-cost/usage-dashboard.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)
- [Enterprise billing with Orb](https://docs.withorb.com/enterprise/enterprise-billing.md)
- [Managing enterprise credits](https://docs.withorb.com/enterprise/managing-credits.md)
- [Migrating from Stripe Billing](https://docs.withorb.com/migration-guides/stripe-billing.md)
- [Request idempotency](https://docs.withorb.com/api-reference/idempotency.md)
- [Pagination](https://docs.withorb.com/api-reference/pagination.md)
- [Error responses](https://docs.withorb.com/api-reference/error-responses.md)
- [Rate limits](https://docs.withorb.com/api-reference/rate-limits.md)
- [Reliability and scaling](https://docs.withorb.com/api-reference/reliability.md)
- [Cached usage responses](https://docs.withorb.com/api-reference/cached-responses.md)
- [List alerts](https://docs.withorb.com/api-reference/alert/list-alerts.md): This endpoint returns a list of alerts within Orb.
- [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 plan alert](https://docs.withorb.com/api-reference/alert/create-plan-alert.md): This endpoint is used to create alerts at the plan level. Plan level alerts are automatically propagated to all subscriptions associated with the plan. These alerts are scoped to a specific plan version; if no version is specified, the active plan version is used.
- [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.
- [Update alert](https://docs.withorb.com/api-reference/alert/update-alert.md): This endpoint updates the thresholds of an alert. On cost alerts it also updates `price_filters`, and on subscription-scoped grouped cost alerts `threshold_overrides`; omitting either leaves it unchanged, and an empty list clears it.
- [Delete alert](https://docs.withorb.com/api-reference/alert/delete-alert.md): This endpoint deletes a subscription or customer-scoped alert. The alert is soft-deleted: it stops firing immediately and no longer appears in fetch or list responses, while the underlying record is retained internally for audit.
- [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 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 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.
- [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.
- [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).
- [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.
- [Delete credit block](https://docs.withorb.com/api-reference/credit/delete-credit-block.md): This endpoint deletes a credit block by its ID.
- [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.
- [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 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.
- [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.
- [List top-ups by external ID](https://docs.withorb.com/api-reference/credit/list-top-ups-by-external-id.md)
- [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 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.
- [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 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.
- [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.
- [List top-ups](https://docs.withorb.com/api-reference/credit/list-top-ups.md)
- [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.
- [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.
- [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 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 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).
- [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.
- [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)).
- [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).
- [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…
- [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). By default, creating a new session invalidates any other active portal sessions for the cu…
- [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.
- [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.
- [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…
- [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…
- [List balance transactions](https://docs.withorb.com/api-reference/customer/list-balance-transactions.md): ## The customer balance
- [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.
- [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…
- [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). By default, creating a new session invalidates any other active portal sessions for the cu…
- [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.
- [List dimensional price groups](https://docs.withorb.com/api-reference/dimensional-price-group/list-dimensional-price-groups.md)
- [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 by external ID](https://docs.withorb.com/api-reference/dimensional-price-group/fetch-dimensional-price-group-by-external-id.md)
- [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.
- [Fetch dimensional price group](https://docs.withorb.com/api-reference/dimensional-price-group/fetch-dimensional-price-group.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.
- [List backfills](https://docs.withorb.com/api-reference/event/list-backfills.md): This endpoint returns a list of all backfills in a list format.
- [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:
- [Fetch backfill](https://docs.withorb.com/api-reference/event/fetch-backfill.md): This endpoint is used to fetch a backfill given an identifier.
- [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`.
- [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).
- [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).
- [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.
- [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.
- [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:
- [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.
- [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.
- [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.
- [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.
- [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…
- [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.
- [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.
- [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.
- [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.
- [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…
- [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.
- [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.
- [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.
- [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.
- [Update item](https://docs.withorb.com/api-reference/item/update-item.md): This endpoint can be used to update properties on the Item.
- [Archive item](https://docs.withorb.com/api-reference/item/archive-item.md)
- [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 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 licenses](https://docs.withorb.com/api-reference/license/list-licenses.md): This endpoint returns a list of all licenses for a subscription.
- [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.
- [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 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.
- [Fetch license](https://docs.withorb.com/api-reference/license/fetch-license.md): This endpoint is used to fetch a license given an identifier.
- [Deactivate license](https://docs.withorb.com/api-reference/license/deactivate-license.md): This endpoint is used to deactivate an existing license.
- [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.
- [List metrics](https://docs.withorb.com/api-reference/metric/list-metrics.md): This endpoint is used to list [metrics](/core-concepts#metric). It returns information about the metrics including its name, description, and item.
- [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 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.
- [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.
- [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 next…
- [Create plan](https://docs.withorb.com/api-reference/plan/create-plan.md): This endpoint allows creation of plans including their prices.
- [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.
- [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.
- [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.
- [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 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.
- [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.
- [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.
- [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.
- [Fetch migration](https://docs.withorb.com/api-reference/plan/fetch-migration.md)
- [Cancel migration](https://docs.withorb.com/api-reference/plan/cancel-migration.md): This endpoint cancels a migration.
- [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.
- [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.
- [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.
- [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).
- [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…
- [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.
- [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.
- [Fetch price](https://docs.withorb.com/api-reference/price/fetch-price.md): This endpoint returns a price given an identifier.
- [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.
- [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.
- [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.
- [Fetch subscription change](https://docs.withorb.com/api-reference/subscription-change/fetch-subscription-change.md): This endpoint returns a subscription change given an identifier.
- [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.
- [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).
- [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.
- [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.
- [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.
- [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).
- [Redeem Coupon](https://docs.withorb.com/api-reference/subscription/redeem-coupon.md): Redeem a coupon effective at a given time.
- [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.
- [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 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.
- [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; it is not possible to unschedule a single plan change if multiple are scheduled.
- [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 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).
- [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.
- [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…
- [Overview](https://docs.withorb.com/integrations-and-exports/introduction.md)
- [Adyen](https://docs.withorb.com/integrations-and-exports/adyen.md)
- [Overview](https://docs.withorb.com/integrations-and-exports/stripe.md)
- [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
- [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
- [Overview](https://docs.withorb.com/integrations-and-exports/salesforce/index.md)
- [Sync Orb data to Salesforce](https://docs.withorb.com/integrations-and-exports/salesforce/salesforce-crm.md)
- [Provision in Orb from Salesforce](https://docs.withorb.com/integrations-and-exports/salesforce/salesforce-cpq.md)
- [Schema](https://docs.withorb.com/integrations-and-exports/salesforce/schema.md)
- [QuickBooks](https://docs.withorb.com/integrations-and-exports/quickbooks.md)
- [Overview](https://docs.withorb.com/integrations-and-exports/netsuite-overview.md)
- [Getting started: NetSuite Integration setup](https://docs.withorb.com/integrations-and-exports/netsuite-getting-started.md)
- [What Is Synced](https://docs.withorb.com/integrations-and-exports/netsuite-what-is-synced.md)
- [How It's Synced](https://docs.withorb.com/integrations-and-exports/netsuite-how-its-synced.md)
- [Sync Reconciliation And Troubleshooting](https://docs.withorb.com/integrations-and-exports/netsuite-sync-reconciliation-and-troubleshooting.md)
- [Recognizing Credit Drawdown](https://docs.withorb.com/integrations-and-exports/netsuite-credit-drawdown.md)
- [Best Practices for Testing](https://docs.withorb.com/integrations-and-exports/best-practices-for-testing.md)
- [NetSuite (Legacy)](https://docs.withorb.com/integrations-and-exports/netsuite_legacy.md)
- [Bill.com](https://docs.withorb.com/integrations-and-exports/billcom.md)
- [Overview](https://docs.withorb.com/overview-1.md)
- [Anrok](https://docs.withorb.com/anrok.md)
- [Avalara (AvaTax)](https://docs.withorb.com/untitled-page.md)
- [Numeral](https://docs.withorb.com/numeral.md)
- [Sphere](https://docs.withorb.com/sphere.md)
- [Stripe](https://docs.withorb.com/stripe.md)
- [TaxJar](https://docs.withorb.com/tax-jar.md)
- [Webhooks](https://docs.withorb.com/integrations-and-exports/webhooks.md)
- [Summary webhooks](https://docs.withorb.com/integrations-and-exports/summary-webhooks.md)
- [Cloud marketplaces](https://docs.withorb.com/integrations-and-exports/cloud-marketplaces.md)
- [Third-party managed integrations](https://docs.withorb.com/integrations-and-exports/third-party-integrations.md): Externally created and maintained wrappers, connectors, and integrations.

## 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)