Create invoice
Creates a one-off invoice in open status. Provide exactly one of customerId or externalCustomerId. When paymentAccountId is omitted or null, one of the customer’s payment accounts is used.
Authorizations
API Key Authentication.
Body
Schema for creating a one-off invoice. Exactly one of customerId or externalCustomerId must be provided. When paymentAccountId is omitted or null, one of the customer payment accounts is used.
A unique idempotency key associated with the invoice.
1^[a-zA-Z0-9_-]+$The closing date of the invoice. It represents the end date of the period covered by the invoice.
The memo to attach to the invoice.
The unique identifier of the customer in our system that this invoice will be associated with.
The external identifier of the customer that this invoice will be associated with.
^[a-zA-Z0-9_-]+$The unique identifier of the payment account that will be used as the billing account. When omitted or null, one of the customer payment accounts is used.
Response
Schema representing an invoice. Monetary amounts are integers in cents.
The unique identifier of the invoice in our system.
A unique key that identifies the invoice for idempotent creation. Supplied by the caller for one-off invoices; generated by the billing engine for contract invoices.
The unique identifier of the customer this invoice bills.
The unique identifier of the customer payment account used as the billing account for this invoice.
The unique identifier of the contract that generated this invoice. Null for invoices not generated from a contract (e.g. one-off and imported invoices).
The sequence of the invoice's billing cycle within its contract, assigned when the cycle is created: 1 for the contract's first cycle, 2 for the second, and so on. Invoices billing the same cycle (e.g. a split across payment accounts, or a replacement) share it. Null for invoices not generated from a contract.
x >= 1Snapshot of the legal entity issuing the invoice (the seller), captured at invoice creation.
Snapshot of the billed party (the legal entity behind the customer payment account), captured at invoice creation.
How the originating contract distributes charges across payment accounts: single bills a single payment account; percent_split divides the total between payment accounts by configured percentages; subsidiary_usage_split divides it according to each subsidiary's usage.
single, percent_split, subsidiary_usage_split When the invoice amounts were last computed by the billing engine. Null when the invoice has never been calculated.
Human-readable invoice number, built from the customer's invoice prefix plus a sequential counter.
"ACMEI-0042"
The closing date of the invoice. It represents the end date of the period covered by the invoice.
Free-form memo attached to the invoice. Null when absent.
Sum of the line item subtotals before adjustments, in cents.
Net amount of all adjustments applied to the invoice line items (discounts and allocation offsets), in cents. Negative when adjustments reduce the amount owed.
Final invoice amount, in cents: subtotalAmount + adjustmentAmount.
The discount portion of adjustmentAmount, in cents (sum of monetary discount adjustments only). Negative when discounts were applied.
Current status of the invoice lifecycle: open (accumulating charges, editable), in_review (flagged for manual review before issuing), issued (finalized and issued to the customer), synced (registered in the external ERP/payment provider), pending (a payment was initiated and awaits settlement), paid, overdue (unpaid past the due date), canceled, or failed (an issue/sync attempt failed and needs attention).
open, in_review, issued, synced, pending, paid, overdue, canceled, failed Whether the invoice contents are locked against edits. Derived from status: issued, synced, pending, paid, overdue, and canceled invoices are locked; open, in_review, and failed invoices are editable.
Reason for the most recent failure on the invoice (e.g. an ERP sync or payment issue). Null when the invoice has no active failure.
How the invoice originated: contract (generated by a contract billing cycle), one_off (created manually or through the API), or import (ingested from an external system).
contract, one_off, import Whether the invoice is issued automatically when its billing cycle closes, without manual review.
Outstanding amount due on the invoice, in cents. Null when not tracked.
Payment due date of the invoice. Null when no due date is set (e.g. before the invoice is issued).
Line item groups on the invoice. Each group gathers the line items generated from one plan instance (or created as a group on one-off invoices).
Line items that do not belong to any line item group (e.g. contract-level minimum commitments, additional charges, and ungrouped one-off items).