> ## Documentation Index
> Fetch the complete documentation index at: https://help.trykarat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Invoices API

> Create invoices, track payment status, download PDFs, cancel invoices, and send reminders.

Use your [Karat API key](/developers/authentication) with `Authorization: Bearer <api-key>`. Invoice operations use the same production base URL as payouts: `https://payouts.api.trykarat.com`. Requests access invoices belonging to the key's organization.

| Operation | Method and path |
| - | - |
| Create an invoice | `POST /invoices` |
| List invoices | `GET /invoices` |
| Get an invoice | `GET /invoices/{id}` |
| Get a temporary PDF download link | `GET /invoices/{id}/pdf` |
| Cancel an invoice | `PUT /invoices/{id}/cancel` |
| Send an invoice reminder | `POST /invoices/{id}/remind` |

The **Invoices** group in the API reference contains the request and response schemas for each operation.

## Create an invoice

All monetary fields use **integer cents**. For example, `unitPrice: 12500` means \$125.00. Supply line-item descriptions, positive integer quantities, and nonnegative integer unit prices. The API computes each amount and the invoice total; do not supply your own total.

Before creating an invoice:

* Configure your invoice sender name and email in the dashboard, or provide both in `sender`.
* Supply `destinationAccountId` when automatic reconciliation is disabled in invoice settings. Replace the example UUID below with an eligible account in your organization.
* Use real calendar dates in `YYYY-MM-DD` format; `dueDate` must be on or after `invoiceDate`.
* Use an invoice number of 1–50 characters, without `/`, `\`, or `..`.

```bash theme={null}
curl --request POST 'https://payouts.api.trykarat.com/invoices' \
  --header "Authorization: Bearer $KARAT_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "invoiceNumber": "INV-2026-001",
    "recipient": {
      "name": "Acme Inc",
      "email": "billing@example.com"
    },
    "lineItems": [
      { "description": "Design services", "quantity": 2, "unitPrice": 12500 }
    ],
    "invoiceDate": "2026-10-05",
    "dueDate": "2026-11-04",
    "sender": { "name": "Example Studio", "email": "billing@example.org" },
    "destinationAccountId": "4f266e59-5dae-49f7-9ef9-9bdf6d2b7c86",
    "sendEmailToRecipient": false
  }'
```

The API reuses an invoice recipient in your organization with the same email, or creates one. Email addresses are trimmed and lowercased. An optional `recipient.address` and up to 20 `recipient.ccEmails` can be included.

Email delivery is **off by default**. Set `sendEmailToRecipient: true` to request delivery. A successful creation returns HTTP `201` with the invoice in `data`, including `emailSent`; the example's computed total is `25000` cents.

Optional `payerMemo` and `paymentInstructions` fall back to your configured defaults when omitted or blank. You can also supply a `poNumber`.

## List and retrieve

```bash theme={null}
curl 'https://payouts.api.trykarat.com/invoices?status=open&limit=25&offset=0' \
  --header "Authorization: Bearer $KARAT_API_KEY"
```

Results are ordered newest first by creation time. The response contains `data` (an invoice array) and `meta` with `total`, `limit`, and `offset`. The default page size is 100; larger limits are clamped to 100. The offset defaults to 0.

Supported status filters are `open`, `paid`, `paid_via_stripe`, `overdue`, and `cancelled`. Omit `status` to return all statuses.

`GET /invoices/{id}` returns one invoice in `data`. Replace `{id}` with the invoice UUID returned by creation or listing. Amounts such as `total`, `paidAmount`, and line-item prices and amounts are in cents. Optional fields such as `paymentAccount` can be `null`.

## Download a PDF

`GET /invoices/{id}/pdf` returns JSON containing `data.url` and `data.expiresIn`, not PDF bytes. Open the URL to download the PDF. The link expires after **900 seconds (15 minutes)**; request a fresh link when needed. An invoice that cannot be found, or has no PDF recorded, returns `404`.

## Cancel or remind

Both operations take the invoice UUID in the path and require no request body.

* `PUT /invoices/{id}/cancel` returns `data.id` and `data.status: "cancelled"`.
* `POST /invoices/{id}/remind` returns `data.success` and may include `notificationId` and `reason`. Check `success` and `reason` even on HTTP `200` to determine whether a reminder was sent.

Only `open` and `overdue` invoices can be cancelled or reminded. Other statuses return `400`; cancelling an already cancelled invoice also returns `400`.

## Errors and retries

Invalid input returns `400`, missing or invalid credentials return `401`, and an invoice that cannot be found within your organization returns `404`. Errors use the standard `error.message` envelope described in [Pagination and errors](/developers/pagination-and-errors).

Invoice creation does not accept the payout batch `idempotencyKey` field. After an uncertain creation response, check existing invoices before retrying; do not assume the payout retry contract applies to invoices.