Read billing data

Use this guide to read invoices and invoice items and to interpret amount units.

List /invoices/ for invoice totals and /invoice-items/ for item-level amounts. Filter by client_id or issue dates before paginating. Use an invoice UUID, not a numeric line-item ID, when retrieving /invoices/{id}/.

How invoices, items and discount codes connect

Color and shape show what kind of resource a box is. Teal rectangles are set up by the studio, purple pills are held by a client, amber rounded boxes are records of something that happened, and the grey hexagon is the client. A solid arrow starts at the resource that holds an ID and ends at the resource the ID refers to. A dotted arrow is a relationship without an ID field.

%%{init: {"flowchart": {"curve": "basis", "nodeSpacing": 45, "rankSpacing": 60, "padding": 14}}}%%
flowchart LR
    client{{"<b>Client</b><br/>/clients/"}}
    invoice("<b>Invoice</b><br/>/invoices/")
    item("<b>Invoice item</b><br/>/invoice-items/")
    code["<b>Discount code</b><br/>/coupons/"]
    usage("<b>Discount code usage</b><br/>/coupon-usages/")
    invoice -->|"client_id"| client
    item -->|"invoice_id"| invoice
    usage -->|"coupon_id"| code
    usage -->|"invoice_id"| invoice
    usage -->|"client_id"| client
    class client person
    class code definition
    class invoice,item,usage record
    classDef definition fill:#beede5,stroke:#21837d,stroke-width:2px,color:#0f3d39
    classDef held fill:#ece4f8,stroke:#6b4fa3,stroke-width:2px,color:#35205f
    classDef record fill:#fef3c7,stroke:#d97706,stroke-width:2px,color:#5e2a0c
    classDef person fill:#e5eaea,stroke:#565e5d,stroke-width:2px,color:#1e2323
    linkStyle default stroke-width:1.5px

Every amount is a decimal string in major currency units, and every rate a decimal-string percentage. See Dates, time zones and amounts.

Field family	Representation
Invoice total_amount, paid_amount, pending_amount, outstanding_amount, and the nested line_items.data amounts and tax amounts	Decimal strings in major currency units: "49.00" means EUR 49.00 when currency=EUR.
Invoice line tax rate, product tax_rate	Percentages: "20.000" means 20%, not 0.20.
Gift-card fixed_amount	Decimal string in major currency units.
Gift-card minimum_amount, maximum_amount	Decimal strings of whole amounts: "10.00". An amount with cents is refused.

For subscription billing, interval_unit is day, week, month or year. recurrence_basis is the number of these units between recurring billing dates; for example, 2 and month describe a two-month interval.