Retainers API

A retainer invoice is a request for money up front, before the work it covers is billed. When the client pays one, the payment adds to their retainer balance, and invoices set to draw against that balance spend it down.

Retainer invoices are kept apart from ordinary invoices. They do not appear under Invoices and ordinary invoices do not appear here. A retainer carries the same fields as an invoice otherwise, so the Invoices page describes its statuses, item types, and tax fields.

Get All Retainers

GET /api/v2/retainers

Accepts status (draft, open, paid, pending, cancelled), from_date, to_date, updated_since, sort (number, date, created_at, due_date), and page.

{
  "page_size": 30,
  "page_count": 1,
  "total_count": 2,
  "retainers": [
    {
      "id": 41,
      "number": "R-0002",
      "title": "Q3 retainer",
      "client_id": 7,
      "currency_code": "USD",
      "date": "2026-07-01",
      "due_date": "2026-07-15",
      "status": 5,
      "subtotal": 5000.0,
      "total_cost": 5000.0,
      "balance": 0.0,
      "invoice_items": [ ... ],
      "payments": [ ... ]
    },
    ...
  ],
  "retainer_balances": {
    "7": { "USD": 3200.0 }
  }
}

retainer_balances is what each client on this page has left on account. It is keyed by client id and then by currency code, because a client may hold a balance in more than one currency. A client with nothing left is left out.

Get a Client's Retainers

GET /api/v2/clients/:client_id/retainers

The same shape, for one client. Here retainer_balances is that client's balances keyed by currency code alone.

{
  "page_size": 30,
  "page_count": 1,
  "total_count": 2,
  "retainers": [ ... ],
  "retainer_balances": { "USD": 3200.0 }
}

Get a Single Retainer

GET /api/v2/retainers/:id

Create a Retainer

POST /api/v2/retainers

Line items go in new_invoice_items, as with invoices. A retainer asks for payment before there is work to bill, so it cannot be attached to an estimate, a deposit, or a project.

{
  "invoice": {
    "client_id": 7,
    "title": "Q4 retainer",
    "date": "2026-10-01",
    "currency_code": "USD"
  },
  "new_invoice_items": [
    { "title": "Q4 retainer", "quantity": 1, "price": 5000 }
  ]
}

Update a Retainer

PUT /api/v2/retainers/:id

Delete a Retainer

DELETE /api/v2/retainers/:id

Send A Retainer

POST /api/v2/retainers/:id/messages

{
  "recipients": ["abc@example.com", "xyz@example.com"],
  "subject": "Subject for the retainer",
  "message": "Body message for the retainer",
  "send_copy": 1,
  "attach_pdf": 1
}

Required Fields: recipients - an array of email addresses. (HTTP 422 on failure)
Encouraged Fields: subject, message are strongly encouraged, since this is what displays in the email, but it is not required.
Optional Fields: send_copy optionally allows the sending user (dependent on API Token used) to receive a copy of the email, attach_pdf allows an optional PDF to be attached.

An address that is not yet a contact of the client becomes one. Each recipient gets their own link to view and pay it. Sending marks the retainer sent.

Payments

GET /api/v2/retainers/:retainer_id/payments

The invoice only asks. Recording a payment against it is what adds to the client's balance. See Payments.