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 propertyinvoicing_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 apartially_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.