> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# The invoice object
> Bill a customer for pending charges and collect payment.
```json The invoice object theme={null}
{
"id": "inv_01JEXAMPLE2K8V4N9C6M1Q7R",
"object": "invoice",
"number": null,
"customer": "cus_01JEXAMPLE2K8V4N9C6M1Q7R",
"subscription": null,
"status": "draft",
"collection_method": "charge_automatically",
"currency": "usd",
"total": 2500,
"amount_paid": 2500,
"amount_remaining": 0,
"hosted_invoice_url": null,
"livemode": false
}
```
An Invoice (`inv_…`) bills a [customer](/api-reference/customers). Your server creates one-off invoices,
and a [subscription](/api-reference/subscriptions) generates one at each period boundary. An invoice
item (`ii_…`) is a pending charge recorded against a customer. When you create an invoice for that
customer, every pending item in the invoice currency is drained onto the new draft as a line (`il_…`).
See [Invoices](/guides/invoices) for the full flow.
A draft can be edited freely. Finalizing it assigns a gapless, sequential number per merchant and mode
(for example `INV-000001`), applies tax, freezes the lines, and opens the invoice. Drafts carry no number,
so an abandoned draft never consumes one. A paid invoice can be offset with a [credit note](/api-reference/credit-notes).
Platforms can create and manage billing for connected accounts: see [Billing for connected accounts](/guides/connect-billing).
## Attributes
The invoice id (`inv_…`).
The gapless per-merchant number, assigned at finalize. Null while draft.
The billed customer (`cus_…`), set at creation and immutable.
The subscription that generated this invoice (`sub_…`). Absent for one-off invoices created directly against a customer.
One of `draft` (being built, lines mutable, never customer-visible), `open` (finalized, lines frozen, awaiting payment), `paid` (terminal; reachable from `open`, from `uncollectible` via a late payment, or directly at finalize when the total is zero), `void` (terminal; requires `amount_paid` of zero), or `uncollectible` (written off; not terminal, since a late payment can still move it to `paid`).
One of `charge_automatically` (charged automatically against the pinned payment method) or `send_invoice` (the buyer pays through the hosted invoice page, with an optional `due_date`).
Three-letter ISO currency code. USD, EUR, and GBP are supported; all use 2-decimal minor units.
`subtotal` plus `tax` minus discounts, in minor units. Discounts can reduce this to zero but never below it.
The cumulative amount paid so far, in minor units.
`total` minus `amount_paid`, in minor units.
The buyer-facing hosted invoice page URL. Present once the invoice has been finalized and hosted invoicing is enabled for the deployment; null on drafts or when hosted invoicing is not configured.
See every field in the response of [Retrieve an invoice](/api-reference/invoices/retrieve-an-invoice).
## Endpoints
| Endpoint | Use it for |
| - | - |
| [Create an invoice item](/api-reference/invoice-items/create-an-invoice-item) | Record a pending charge against a customer. |
| [Retrieve an invoice item](/api-reference/invoice-items/retrieve-an-invoice-item) | Fetch one invoice item. |
| [Update an invoice item](/api-reference/invoice-items/update-an-invoice-item) | Change a pending invoice item. |
| [Delete an invoice item](/api-reference/invoice-items/delete-an-invoice-item) | Remove a pending invoice item. |
| [Create an invoice](/api-reference/invoices/create-an-invoice) | Create a draft for a customer. |
| [List invoices](/api-reference/invoices/list-invoices) | Review invoices, optionally filtered by status. |
| [Retrieve an invoice](/api-reference/invoices/retrieve-an-invoice) | Check the current status and amounts. |
| [Download an invoice PDF](/api-reference/invoices/download-an-invoice-pdf) | Render the invoice and its recorded payments as a PDF. |
| [Update an invoice's payment method](/api-reference/invoices/update-an-invoices-payment-method) | Set or replace the payment method pinned for collection on an open invoice. |
| [Add a line to a draft invoice](/api-reference/invoices/add-a-line-to-a-draft-invoice) | Add a line while the invoice is a draft. |
| [Remove a line from a draft invoice](/api-reference/invoices/remove-a-line-from-a-draft-invoice) | Remove a line while the invoice is a draft. |
| [Finalize an invoice](/api-reference/invoices/finalize-an-invoice) | Move a draft to open, or to paid when the total is zero. |
| [Collect payment on an invoice](/api-reference/invoices/collect-payment-on-an-invoice) | Charge an open `charge_automatically` invoice against the customer's saved card. |
| [Void an invoice](/api-reference/invoices/void-an-invoice) | Void an open invoice that has taken no payment. |
| [Mark an invoice uncollectible](/api-reference/invoices/mark-an-invoice-uncollectible) | Write off an open invoice and keep the balance for reporting. |
| [List an invoice's payment attempts](/api-reference/invoices/list-an-invoices-payment-attempts) | See the collection attempts recorded for an invoice, newest first. |
## Statuses
| Status | Meaning |
| - | - |
| `draft` | Being built. Lines are mutable and the invoice is never customer-visible. |
| `open` | Finalized, lines frozen, awaiting payment. |
| `paid` | Terminal. Reachable from `open`, from `uncollectible` through a late payment, or directly at finalize when the total is zero. |
| `void` | Terminal. Requires `amount_paid` of zero. |
| `uncollectible` | Written off. Not terminal, because a late payment can still move it to `paid`. |
## Collection methods
| Method | Behavior |
| - | - |
| `charge_automatically` | Charged automatically against the pinned payment method. |
| `send_invoice` | The buyer pays through the hosted invoice page, with an optional `due_date`. |
## Payment attempts
Each automatic collection attempt is recorded as an `invoice_payment_attempt` with a status of `pending`, `succeeded`, `failed`, or `blocked`. `pending` means the final outcome is not known yet. Retrieve the attempts again before retrying.
## Notes
* Live invoice numbers use `INV-000001` style labels. Test invoice numbers use `TEST-INV-000001`.
* An authorized platform can call every invoice and invoice item endpoint for a connected account by sending `Ionic-Account`. See [Bill a connected account](/guides/connect-billing#bill-a-connected-account).
* Mutating endpoints accept an optional `Idempotency-Key` header. See [Idempotency](/api-reference/idempotency).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.