Skip to main content
Use your Karat API key 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. 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 ...
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

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