Skip to main content
POST
Cancel invoice

Authorizations

X-API-KEY
string
header
required

API Key Authentication.

Path Parameters

invoiceId
string<uuid>
required

The unique identifier of the invoice to cancel.

Response

Schema representing an invoice. Monetary amounts are integers in cents.

id
string<uuid>
required

The unique identifier of the invoice in our system.

idempotencyKey
string
required

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.

customerId
string<uuid>
required

The unique identifier of the customer this invoice bills.

paymentAccountId
string<uuid>
required

The unique identifier of the customer payment account used as the billing account for this invoice.

contractId
string<uuid> | null
required

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).

contractInvoiceSequence
integer | null
required

The number of the invoice within its contract, in the order that Aira created the contract's invoices: 1 for the first, 2 for the next, and so on. Every invoice gets its own number, including each invoice of a split across payment accounts and the replacement of a reopened invoice, and a number never changes and is never reused. Null for invoices without a contract.

Required range: x >= 1
issuingAccount
object
required

Snapshot of the legal entity issuing the invoice (the seller), captured at invoice creation.

billingAccount
object
required

Snapshot of the billed party (the legal entity behind the customer payment account), captured at invoice creation.

invoiceAllocationStrategy
enum<string>
required

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.

Available options:
single,
percent_split,
subsidiary_usage_split
lastCalculatedAt
string<date-time> | null
required

When the invoice amounts were last computed by the billing engine. Null when the invoice has never been calculated.

invoiceNumber
string
required

Human-readable invoice number, built from the customer's invoice prefix plus a sequential counter.

Example:

"ACMEI-0042"

invoiceDate
string<date>
required

The date of the invoice. On a contract invoice it is the date of its billing act: the first day of the first billing cycle that the contract invoices for an activation invoice, and the last day of the billing cycle for a closing invoice. Its line items state the periods that it bills. On a one-off or imported invoice it is the date given when the invoice was created.

memo
string | null
required

Free-form memo attached to the invoice. On contract invoices, it reads "Período a " with the period of the line item that bills most often, such as the month when a monthly fee is billed with an annual fee. When two line items bill equally often, it uses the earlier period. Null when absent.

subtotalAmount
number
required

Sum of the line item subtotals before adjustments, in cents.

adjustmentAmount
number
required

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

totalAmount
number
required

Final invoice 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.

status
enum<string>
required

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).

Available options:
open,
in_review,
issued,
synced,
pending,
paid,
overdue,
canceled,
failed
isLocked
boolean
required

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.

failureReason
string | null
required

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.

source
enum<string>
required

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).

Available options:
contract,
one_off,
import
autoIssue
boolean
required

Whether the invoice is issued automatically when its billing cycle closes, without manual review.

amountDue
number | null
required

Outstanding amount due on the invoice, in cents. Null when not tracked.

dueDate
string<date> | null
required

Payment due date of the invoice. Null when no due date is set (e.g. before the invoice is issued).

lineItemGroups
object[]
required

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).

standaloneLineItems
object[]
required

Line items that do not belong to any line item group (e.g. contract-level minimum commitments, additional charges, and ungrouped one-off items).

customFields
object
required

The values of the tenant's custom fields for invoices, keyed by the key of each custom field. The object is empty when the invoice holds no value. A user edits them in the billing app, in any status of the invoice, and no public route writes them.

Example: