Invoices

List invoices

GET /api/v1/invoices

Any role. Returns the organization's invoices, newest first, each with its client ({ id, name }). Owner and admin keys get every invoice. A member's key doesn't get invoices with a line on a confidential project the member isn't on.

curl "https://<your-instance>/api/v1/invoices?status=SENT" \
  -H "Authorization: Bearer ch_live_..."

{
  "invoices": [
    {
      "id": "cm9...",
      "number": "INV-0042",
      "status": "SENT",
      "issueDate": "2026-08-01T00:00:00.000Z",
      "dueDate": "2026-08-31T00:00:00.000Z",
      "paymentTerms": "NET30",
      "subtotal": "5250",
      "taxAmount": "0",
      "total": "5250",
      "currency": "USD",
      "kind": "STANDARD",
      "amountPaid": "2000.00",
      "creditApplied": "0.00",
      "balanceDue": "3250.00",
      "paidAt": null,
      "firstViewedAt": "2026-08-02T16:40:12.000Z",
      "viewCount": 3,
      "client": { "id": "cm9...", "name": "Fintra Labs" },
      "...": "..."
    }
  ]
}

amountPaid is the sum of the payments recorded on the invoice and creditApplied the client credit applied to it; balanceDue is total minus both (never below 0.00, and 0.00 for a VOID invoice). A partly paid invoice stays SENT until balanceDue reaches 0.00. kind is STANDARD, or DEPOSIT for a deposit invoice. paidAt is when the invoice became paid in full (by hand, or when an online payment went through), or null. firstViewedAt, lastViewedAt and viewCount track when the client opened the invoice. To find overdue invoices, look for SENT invoices whose dueDate has passed (the MCP list_invoices tool returns isOverdue and daysOverdue for you).

Generate an invoice

POST /api/v1/invoices/generate

Owner/admin only. Creates a draft from unbilled time entries, completed milestones, and/or approved expenses, the same as Generate invoice in the app. Returns 201 with { "invoice": { ... } }, including its id, number and computed subtotal, taxAmount and total. Review and send the draft in the app, or with the MCP email_invoice or mark_invoice_sent tools.

At least one of timeEntryIds, milestoneIds, or expenseIds is required. IDs that don't qualify (already invoiced, not billable, on another client's project, and so on) are skipped. The invoice uses the organization's default currency.

curl -X POST https://<your-instance>/api/v1/invoices/generate \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cm9...",
    "timeEntryIds": ["cm9...", "cm9..."],
    "issueDate": "2026-08-01",
    "paymentTerms": "NET30"
  }'

Errors

Bill a set amount

POST /api/v1/invoices/custom

Owner/admin only. Creates a draft for amounts you name rather than logged work: a set fee, a retainer or a deposit, the same as Set amount in the app. Nothing is marked billed. Returns 201 with { "invoice": { ... } }.

curl -X POST https://<your-instance>/api/v1/invoices/custom \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "cm9...",
    "lines": [{ "description": "Initial deposit", "amount": 500 }],
    "deposit": true,
    "issueDate": "2026-10-19",
    "paymentTerms": "DUE_ON_RECEIPT"
  }'

Errors

List an invoice's payments

GET /api/v1/invoices/{id}/payments

Any role that can see the invoice. Returns its amountPaid, creditApplied and balanceDue, plus:

• payments: each with amount, currency, receivedAt, source (MANUAL, STRIPE, MERCURY or QUICKBOOKS), method, reference, note and recordedBy (a name, or null for payments recorded by an integration), newest first.
• creditApplications: client credit applied to the invoice.
• creditNotes: credit notes issued against it.

Returns 404 with Invoice not found. for an invoice in another organization or one the key can't see.

Record a payment

POST /api/v1/invoices/{id}/payments

Owner/admin only. Records money received against a sent invoice, the same as Record payment in the app. The invoice becomes PAID when its balance reaches zero (with the invoice paid alert); a part payment leaves it SENT and sends the part payment received alert. Returns 201 with { "payment": { ... }, "invoice": { ... } }; invoice includes the new amountPaid and balanceDue.

curl -X POST https://<your-instance>/api/v1/invoices/cm9.../payments \
  -H "Authorization: Bearer ch_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 2000, "receivedAt": "2026-08-20", "method": "Wire" }'

Errors

To delete a payment recorded by mistake, use the invoice's Payments card in the app.