Skip to main content
PUT
Update invoice line item

Authorizations

X-API-KEY
string
header
required

API Key Authentication.

Path Parameters

invoiceId
string<uuid>
required

The unique identifier of the invoice the line item belongs to.

lineItemId
string<uuid>
required

The unique identifier of the line item to update.

Body

application/json

Schema for updating a line item on a one-off invoice. When subLineItems is provided, existing sub-items are replaced; when omitted, sub-items are left untouched. When subLineItems is non-empty, the sum of usage × price (rounded to whole cents per row) must equal amount.

startDate
string<date>
required

Start of the period covered by the line item.

endDate
string<date>
required

End of the period covered by the line item.

amount
number
required

Amount billed by the line item, in cents.

name
string | null

Optional line item name; defaults to the item name (or product name as fallback) when null.

subLineItems
object[]

When provided, existing sub-items are replaced. The sum of usage × price (rounded to whole cents per row) must equal amount.

Response

Schema representing an invoice line item. Monetary amounts are integers in cents; the price breakdown lives in subLineItems.

id
string<uuid>
required

The unique identifier of the line item in our system.

idempotencyKey
string
required

A unique key that identifies the line item within the invoice. Supplied by the caller for one-off line items; generated by the billing engine otherwise.

customerId
string<uuid>
required

The unique identifier of the customer whose consumption this line item bills. On split or consolidated invoices it may be a subsidiary of the invoice's customer.

productId
string<uuid>
required

The unique identifier of the product this line item belongs to.

resourceId
string<uuid> | null
required

The unique identifier of the metered resource behind a usage_based line item. Null for line items not driven by resource usage.

licenseId
string<uuid> | null
required

The unique identifier of the license behind a license_based line item. Null for line items not driven by a license count.

lineItemGroupId
string<uuid> | null
required

The unique identifier of the line item group containing this line item. Null for standalone line items.

name
string
required

Display name of the line item as it appears on the invoice.

scope
enum<string>
required

What the line item charges for: usage_based (metered resource consumption), license_based (a license's reported count billed in full), fixed (recurring fixed charge of a plan), minimum_commitment (plan-level minimum top-up), contract_minimum_commitment (contract-level minimum top-up), credit_purchase (credit pool top-up), additional_charge (extra charge added manually), one_off (line item of a one-off invoice), or tax_gross_up (tax gross-up charge).

Available options:
credit_purchase,
contract_minimum_commitment,
minimum_commitment,
fixed,
usage_based,
license_based,
additional_charge,
one_off,
tax_gross_up
startDate
string<date>
required

Start of the period covered by this line item.

endDate
string<date>
required

End of the period covered by this line item.

totalUsage
number | null
required

Total usage billed by the line item, in the unit given by usageFormat. Null for line items without usage (e.g. fixed charges).

usageFormat
enum<string> | null
required

How to read totalUsage and the sub-line usage values: unit means a count of resource units; currency means a monetary base amount in cents. Null when the line item has no usage.

Available options:
unit,
currency,
null
subtotalAmount
number
required

Line item amount before adjustments, in cents (sum of its sub-line item amounts).

adjustmentAmount
number
required

Net amount of the adjustments applied to this line item (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed.

totalAmount
number
required

Final line item amount, in cents: subtotalAmount + adjustmentAmount.

discountAmount
number
required

The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied.

metadata
Fixed · object
required

Pricing metadata for the line item, where the shape is keyed by type. Always present, but null for line items without pricing metadata: fixed, credit_purchase, additional_charge, one_off, and tax_gross_up. It is populated only for usage_based, license_based, minimum_commitment, and contract_minimum_commitment line items.

subLineItems
object[]
required

Breakdown of the line item amount into priced rows (included quantities, unit/package/tier prices, prorations, companions). Empty for line items without a breakdown.

adjustments
object[]
required

Adjustments applied on top of the line item subtotal, such as discounts and allocation offsets.

itemId
string<uuid> | null

The unique identifier of the catalog item this line bills. Null for line items not backed by a catalog item.