> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.mitu.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mitu.ai/_mcp/server. # Invoices Use invoices when you need a formal billing record rather than a simple one-time payment. An invoice can contain multiple line items, tax, discounts, a due date and your own invoice number, while giving you a lifecycle to track from creation through payment. Invoices are addressed to [recipients](/platform/payments/recipients) and can be paid by either a person or an AI agent. Both payer experiences belong to the same invoice, so your billing record and reconciliation remain consistent regardless of how payment is completed. ## Create an invoice Create an invoice for the person or business you want to bill and provide at least one line item. Name them inline with `recipient`, or pass the `recipientId` of someone you have already saved. **`Create an invoice`** ```bash title="Create an invoice" curl --request POST \ --url https://api.mitu.ai/v1/invoices \ --header "x-api-key: $MITU_API_KEY" \ --header "Idempotency-Key: invoice-INV-2026-441" \ --header "Content-Type: application/json" \ --data '{ "recipient": { "name": "Ada Lovelace", "email": "ada@example.com" }, "invoiceNumber": "INV-2026-441", "description": "Design services, September", "currency": "USD", "lineItems": [ { "name": "Design retainer", "quantity": 1, "amount": 1200.00 }, { "name": "Additional revisions", "description": "3 rounds", "quantity": 3, "amount": 150.00 } ], "taxAmount": 123.75, "discountAmount": 0, "dueAt": "2026-10-01T00:00:00Z" }' ``` ### Parameters | Parameter | Type | Description | | ---------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `recipient` | `object` · conditional | Who to bill, given inline: `name` (required), with an optional `email` and `phone`. Mitu looks for a saved recipient with the same email, then the same phone. If one exists, the invoice goes to them and their saved name is kept. Otherwise a new recipient is saved. | | `recipientId` | `string` · conditional | The ID of a [saved recipient](/platform/payments/recipients), such as `rcp_ds9hazr8jd3l`. | | `lineItems` | `array` · required | The products, services or other charges included on the invoice. Provide at least one line item. Each contains `name`, `quantity` and `amount`, with an optional `description`. | | `currency` | `string` · required | The currency used for the invoice and its line items. | | `invoiceNumber` | `string` | Your own invoice number, up to 50 characters. | | `description` | `string` | Additional context describing what the invoice is for. | | `taxAmount` | `number` | The tax added to the invoice total. The default is `0`. | | `discountAmount` | `number` | The discount deducted from the invoice total. The default is `0`. | | `dueAt` | `string` | The date and time the invoice is due, provided as an ISO 8601 timestamp. | Send exactly one of `recipient` or `recipientId`. Sending neither, or both, returns `400` with `Send exactly one of recipientId or recipient`. The total after tax and discount must be more than zero, or the request returns `400`. To bill someone you have already saved, pass their ID instead: ```json { "recipientId": "rcp_ds9hazr8jd3l", "currency": "USD", "lineItems": [{ "name": "Design retainer", "quantity": 1, "amount": 1200.00 }] } ``` Request fields are camelCase. Response fields are snake_case, the same as payment links. **`Response`** ```json title="Response" { "message": "Invoice created successfully", "data": { "id": "inv_4k2m9x7ptw3c", "invoice_number": "INV-2026-441", "status": "draft", "recipient": { "id": "rcp_ds9hazr8jd3l", "name": "Ada Lovelace", "email": "ada@example.com", "phone": null, "created_at": "2026-09-11T15:00:34.915Z" }, "description": "Design services, September", "line_items": [ { "name": "Design retainer", "quantity": 1, "amount": 1200 }, { "name": "Additional revisions", "description": "3 rounds", "quantity": 3, "amount": 150 } ], "subtotal": "1650.00", "tax_amount": "123.75", "discount_amount": "0.00", "amount": "1773.75", "currency": "USD", "url": { "checkout": "https://mitu.ai/invoice/inv_4k2m9x7ptw3c", "agent": "https://api.mitu.ai/invoice/inv_4k2m9x7ptw3c" }, "due_at": "2026-10-01T00:00:00.000Z", "sent_at": null, "viewed_at": null, "paid_at": null, "created_at": "2026-09-11T15:00:35.102Z" } } ``` `amount` is the total the payer is asked for: `subtotal` plus `tax_amount`, minus `discount_amount`. ### Safe retries Send an `Idempotency-Key` header so a retried request does not bill the same person twice. For 24 hours, a request with the same key and body returns the original invoice instead of creating another. The same key with a different body returns `409`. See [Idempotency](/api-reference/idempotency). ## Invoice lifecycle | Status | What it means | Paying it | | ----------- | ---------------------------------------------------- | ------------------------------------------------------ | | `draft` | Created, not yet sent. You can still edit it. | Not payable. The pay URL returns `409` `not-sent`. | | `sent` | Sent to the recipient. You can still edit it. | Payable. | | `viewed` | The recipient has opened the pay URL. | Payable. | | `overdue` | The due date passed while it was `sent` or `viewed`. | Still payable. The due date does not close an invoice. | | `settling` | A payment is being settled. | Cannot be cancelled. | | `paid` | Paid in full. | Cannot be cancelled. | | `cancelled` | Cancelled by you. | Not payable. The pay URL returns `410` `cancelled`. | A new invoice starts as a draft, so you can review or amend it before making it payable. While it is `draft` or `sent`, update it with `PATCH /v1/invoices/{id}`. The total is recalculated from the line items, tax and discount. Send `recipientId` to address it to a different saved recipient. When the invoice is ready, send it. ```http POST /v1/invoices/{id}/send ``` Sending moves a draft to `sent` and emails the invoice to the recipient, with a button to pay it. If the recipient has no email address, the invoice is still marked sent and you share its `url.checkout` yourself. You can send again while the invoice is `sent`, `viewed` or `overdue` to email a reminder. An invoice moves to `viewed` the first time the recipient opens its pay URL. It moves to `overdue` within a few minutes of its `due_at` passing, if it has not been paid. You can retrieve and manage invoices through the API throughout their lifecycle. ```http GET /v1/invoices GET /v1/invoices/{id} PATCH /v1/invoices/{id} DELETE /v1/invoices/{id}/cancel ``` List invoices with `status` and `recipientId` filters. The list is cursor-paged: pass `meta.next_cursor` as `cursor` to fetch the next page. ```http GET /v1/invoices?recipientId=rcp_ds9hazr8jd3l&status=overdue&limit=20 ``` Cancelling returns the invoice's `id`, `status` and `cancelled_at`. A `paid` or `settling` invoice cannot be cancelled and returns `409`. Keep invoice state in your own system in sync with the API and webhook events rather than relying on what the payer sees in their payment experience. ## Getting an invoice paid An invoice is paid at its own URLs, returned in `url`. A person opens `url.checkout` and pays through the available methods. An AI agent calls `url.agent` and completes the payment through the agent payment flow. Both belong to the same invoice. Use the URLs returned for the invoice rather than constructing them yourself. This keeps your integration independent of how invoice payment URLs are structured. > **No separate invoice for an AI agent** > > You do not need to create another invoice when an AI agent is paying on behalf of the recipient. The same invoice can support both human and agent payment experiences. See [Payment experiences](/platform/payments/payment-experiences) for how human and agent payment entry points work, and [Agent payments](/platform/payments/agent-payments) for the agent payment flow. ## Track invoice events Use webhook events to keep the invoice state in your application up to date. ```text invoice.created invoice.sent invoice.viewed invoice.overdue invoice.paid ``` Every invoice event carries the `recipient`, with its `reference`, so you can record who was billed, and whose recipient it is in your system, without fetching the invoice. `invoice.sent` also says whether the invoice was `emailed`. `invoice.viewed` is emitted once, the first time the recipient opens the invoice. When payment is received, `payment.completed` is also emitted, with `source` set to `invoice` and the same invoice fields as `invoice.paid`. Use the invoice information in the event to associate the payment with the correct billing record. Do not update invoice state based only on a browser redirect or information reported by an AI client. Process verified webhook events or retrieve the current invoice state through the API. See [Events](/platform/webhooks/events) for invoice and payment event payloads. ## Reconcile invoice payments Keep your own invoice number or business reference associated with the invoice so your application can reconcile payments against records it already understands. An invoice being paid and the underlying service being delivered are separate business states. When payment completes, update the billing record and then continue whatever fulfilment process applies to the invoice in your own system. This is especially important when invoice payment triggers another action, such as activating a service, releasing an order or confirming a booking. ## Related #### [Payment experiences](/platform/payments/payment-experiences) Understand payment experiences for people and AI agents. #### [Agent payments](/platform/payments/agent-payments) Understand how AI agents complete payments programmatically. #### [Recipients](/platform/payments/recipients) Save and manage the people and businesses your invoices are addressed to. #### [Webhooks](/platform/webhooks/overview) Keep your application updated as invoice state changes. #### [Events](/platform/webhooks/events) See the events emitted during the invoice lifecycle. #### [Settlement](/platform/payments/settlement) Settle the funds you receive to a bank account or onchain address.