Threshold Invoicing
Subscriptions in Orb can be set up with an invoicing threshold, which is an amount in the invoicing currency (e.g. USD). Specifically, thresholds are always expected to be a positive amount and apply at the full scope of the subscription rather than for individual prices. Note that threshold evaluation only considers usage-based line items. Fixed fees are excluded from threshold calculations to avoid triggering immediate invoicing at the start of the billing period.
Once the threshold for a subscription is reached, a threshold invoice will be generated which will contain all the prices on the subscription. Threshold invoices bypass the reporting grace period and will be issued immediately if eligible for issuance. As a consequence, Orb does not guarantee that all usage corresponding to the line item period on the threshold invoice will be included; any usage that has not yet been ingested will still be billed in the “parent” full invoice (or in a subsequent threshold invoice). If the threshold is not reached by the end of the billing period, a standard invoice will be issued as usual.
The amounts from all threshold invoices will be applied to the appropriate usage line items when the full billing period invoice is issued.
Monitoring the invoicing threshold
The invoicing threshold is monitored in the background. If an account’s usage significantly exceeds the threshold, an invoice may be generated that surpasses the threshold amount. To update the invoicing threshold set the property invoicing_threshold when using the Update Subscription API.
Alerts on subscriptions can be setup to alert when particular thresholds have been reached. See the Alerts API for information on how to setup alerts.
Mechanics of threshold invoicing
As a subscription accrues usage, the invoicing threshold is evaluated constantly and a threshold invoice is generated as soon as Orb detects that the threshold has been reached. Threshold invoices may exceed the exact threshold amount (especially if usage is accruing quickly or reported in large chunks), but will be issued as soon as the threshold is reached. If usage exceeds a multiple of the threshold before a threshold invoice is issued, Orb will issue a single invoice for the full incremental amount.
Note that the invoicing threshold is evaluated on a per-subscription basis. If a customer has multiple subscriptions, each subscription will be evaluated separately.
For a given billing period, each threshold invoice represents a prefix of the total invoice for that period. Specifically, this means that subsequent threshold invoices are always a strict superset of previous threshold invoices, and Orb ensures that the previously invoiced amount is not double-counted by subtracting this out during invoice line item calculations. This means that threshold invoice periods are not disjoint periods, which would otherwise cause incorrect billing behavior in pricing models that have a tiering or allocation component that cannot reset during a single billing period.
Additional Considerations
Do threshold invoices include adjustments like minimums, maximums, and discounts?
Yes. Threshold invoices do account for all adjustments defined on the subscription. However, these adjustments are applied across the full billing period, not at each threshold. For example, a fixed 10 minimum charge will be applied once on the final invoice, not at each threshold issuance.
Will Orb issue a threshold invoice based on credit utilization or overages?
Threshold invoices are triggered based solely on the total invoiced amount across all usage-based line items on the subscription. They are not tied to credit burndown, overages, or any individual price component.
Is there a limit to the number of threshold invoices per billing period?
No. There is no enforced limit to the number of threshold invoices Orb may issue for a subscription in a billing period.
Can I configure a threshold invoice to trigger just once per subscription?
No. Threshold invoicing is always based on the total accrued charges and will trigger every time the threshold is reached. However, you can modify the threshold mid-period using the Update Subscription API if you want to prevent further threshold invoices.
Understanding threshold invoices in the API
On a subscription invoice with threshold invoicing enabled, each invoice line item contains a partially_invoiced_amount field. This field represents the amount that has already been invoiced for that line item as a result of threshold invoicing and so is not included when calculating the amount due on that invoice. See the guide for invoice calculations and the step detailing previously invoiced amounts.