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

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

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:

{
  "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.

{
  "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.

Invoice lifecycle

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.

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.

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.

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.

See Payment experiences for how human and agent payment entry points work, and Agent payments for the agent payment flow.

Track invoice events

Use webhook events to keep the invoice state in your application up to date.

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