Core resources

Invoices

Create an invoice as a draft, issue it (assign a number, go live), or issue and email the client a pay link — all from one call.

Create an invoice#

POST/v1/invoices

Field	Type	Description
clientIdreq	string	Id of an active client in your workspace.
action	"draft" \| "issue" \| "send"	What to do on create. Defaults to `issue`. See below.
dueDatereq	string	When payment is due (ISO-8601).
lineItemsreq	LineItem[]	At least one line. Each: description, quantity, rateCents, taxRate?
issuedAt	string	Override the issue date (ISO-8601).
currency	string	3-letter code; defaults to USD.
notes	string	Client-facing note shown on the invoice.
internalNotes	string	Private note, not shown to the client.
feesWaived	boolean	Waive the payment fee on this invoice.
matterId	string	Legal module: bill under a matter (must belong to the client).

action controls the lifecycle: draft saves it without a number or email; issue (default) assigns a number and makes it live; send also emails the client a pay link. send requires the client to have an email with consent on file, otherwise it returns 422 validation_failed.

Line item shape:

Field	Type	Description
descriptionreq	string	Line description.
quantityreq	number	Positive quantity.
rateCentsreq	integer	Per-unit price in cents (1250 = $12.50).
taxRate	number	Decimal rate, e.g. 0.0825 for 8.25%. Defaults to 0.

Request

curl https://paytrum.com/api/v1/invoices \
  -H "Authorization: Bearer ak_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "66f1a2b3c4d5e6f7a8b9c0d1",
    "action": "issue",
    "dueDate": "2026-07-01",
    "lineItems": [
      { "description": "Design retainer", "quantity": 1, "rateCents": 250000 },
      { "description": "Hosting", "quantity": 12, "rateCents": 1500, "taxRate": 0.0825 }
    ]
  }'

201 Created

{
  "object": "invoice",
  "id": "66f2b3c4d5e6f7a8b9c0d1e2",
  "number": "INV-0042",
  "status": "open",
  "clientId": "66f1a2b3c4d5e6f7a8b9c0d1",
  "currency": "USD",
  "lineItems": [
    { "description": "Design retainer", "quantity": 1, "rateCents": 250000, "taxRate": 0, "lineSubtotalCents": 250000, "lineTaxCents": 0 }
  ],
  "subtotalCents": 268000,
  "taxTotalCents": 1485,
  "totalCents": 269485,
  "balanceCents": 269485,
  "paidCents": 0,
  "dueDate": "2026-07-01T00:00:00.000Z",
  "issuedAt": "2026-06-09T17:04:21.000Z",
  "sentAt": null,
  "publicPayUrl": "https://acme.collect.com/pay/invoice/iv_8f2a…",
  "createdAt": "2026-06-09T17:04:21.000Z",
  "updatedAt": "2026-06-09T17:04:21.000Z"
}

The invoice object#

Amounts are integer cents. number and publicPayUrl are null for drafts and populated once issued. balanceCents is what remains due (totalCents + interest − paidCents − write-offs). Each line carries computed lineSubtotalCents and lineTaxCents.

Retrieve an invoice#

GET/v1/invoices/{id}

curl https://paytrum.com/api/v1/invoices/66f2b3c4d5e6f7a8b9c0d1e2 \
  -H "Authorization: Bearer ak_live_your_key"

List invoices#

GET/v1/invoices

Cursor-paginated, newest first. Query params: limit (1–100, default 25), startingAfter (an id), status (draft, open, partially_paid, paid, overdue, void), and clientId to filter to one client.

curl "https://paytrum.com/api/v1/invoices?status=open&clientId=66f1a2b3c4d5e6f7a8b9c0d1" \
  -H "Authorization: Bearer ak_live_your_key"