Deprecation Notice

The following fields are now deprecated on the line item response and are scheduled for removal in August 2025:

• discount

• maximum

• maximum_amount

• minimum

• minimum_amount
  

These fields have been replaced by the adjustments field, which aggregates all applied adjustments (e.g., discounts, minimums, maximums) into a single structured response for a line item.

New Field Additions

New fields have been introduced in the Invoice APIs to enhance the information available for virtual currencies and provide raw amounts from the Orb system:

• adjusted_subtotal: The amount after adjustments but before any pre-purchase or overage conversion.

• adjustments: A list of all adjustments applied to the line item (e.g., discounts, minimums, maximums). Each adjustment configuration returns an amount corresponding to the value applied.

• credits_applied: Any pre-purchase credits that were used.

• partially_invoiced_amount: Any amount from a partial invoice resulting from threshold invoicing.

Opting Into Improved Invoice Values

Enhanced values for virtual currencies and invoice amounts are available on an opt-in basis. To enable these changes, include the following header in requests to the Invoice API:

Orb-Enable : revised_invoice_fields

These changes will become the default response in May 2025.

Improvements for Virtual Currencies on Invoice Line Items

• quantity: The returned quantity will now reflect usage or fixed fee quantity. Previously, it returned the subtotal amount in virtual currency.

• name: The postscript verbiage (e.g., "overage") will be removed from the name field, returning only the line item name.

• subtotal: The subtotal will now represent the subtotal amount in virtual currency rather than the converted amount in real-world currency.

• sub_line_items: Detailed sub-line item information will now be available for virtual currencies.

Changes to Invoice Line Items Amounts

• amount: The returned amount will now reflect the total after all adjustments have been applied to the line item.

To retrieve the previously returned amount, use the adjustments field to subtract any invoice-level adjustment applied to the line item (i.e., adjustments where is_invoice_level is set to True).

Example Calculation: New Amount vs Old Amount

• Usage quantity: 10

• Unit rate: 5

• Invoice-level amount discount: $10

  Calculation Step	Formula	Example Calculation
  subtotal	usage quantity * unit rate	10 * 5 = 50
  adjusted_subtotal	subtotal - adjustments	50 - 10 = 40
  New amount field	amount with all adjustments and credits applied	40
  Old amount field	amount without invoice-level adjustments	40 - (-10) = 50

  These changes ensure greater clarity and consistency in invoice calculations while improving support for virtual currencies.