Skip to content

Invoices, payments and credit notes

This page explains how the money side of the REST API behaves: what to send, how to retry safely, and what a refusal means. Every route, field and answer is listed in the full API reference, under Invoicing, Payments, Credit Notes and Statements.

Before you build an integration, check whether a workflow can do it: the Accounting task makes documents and records payments with no code. See API Reference.

Keys and rights

Make an API key under your profile's API Keys tab. A key acts as the person who made it, with their rights: making invoices needs Create Invoices, recording payments Pay Invoices, refunds and removing payments Refund and remove payments, and so on (see User rights). Exchange the key for a token with POST /v2/auth/token.

When you make a key, What it can reach can limit it:

Choice The key can reach
Everything (the default) Whatever its person can do.
Only invoices, payments and the books Quotes, invoices, payments, credit notes, statements, the books and banking. Not clients' messages, notes or anything else. Give this to a payment integration or an accountant's tool.
Only invoices, payments and the books, with a higher limit for moving your history in The same, with 600 requests a minute instead of 60, for importing your history from another system.

Payments recorded through an API key have the source api, so you can tell them from ones recorded in the CRM.

Quotes and invoices

The invoice routes live under /v2/clientzone.

Make one: POST /v2/clientzone/createNewInvoice

Send client_id, status (0 a quote, 1 an invoice) and entries, one per line. Useful fields:

Field What it does
document_date The document's own date: YYYY-MM-DD, DD/MM/YYYY, or a date and time (read as that day in the account's timezone). Today when left out.
due_date When an invoice is due. Left out: the account's or the client's payment terms. expiry_date is the old name and still works.
tax_mode 0 tax exclusive, 1 tax inclusive, 2 no tax. Left out: the account's Invoice prices are setting.
reference Free text, such as its number in your old system.
if_reference_exists create (the default) always makes a new one. use gives back the client's existing document with that Reference, so a retry or a re-run import never makes a copy.
expected_total The total it must come to, tax included. Refused if the lines come to something else, and, with use, if the existing document's total is different.
tax_amount The tax as your old system worked it out. A cent or so of rounding is put on the largest line; more is refused.
document_number Keep this number, if no document in the account has it yet (void ones included). Otherwise it gets the next number.
start_automations false makes it without starting Invoice Created workflows: use it for old documents.
entries[].quantity Up to 4 decimal places, such as 1.5.
entries[].discount_percent A percentage off the line, before tax.
entries[].long_description The details printed under the line.
entries[].ledger_account_id, entries[].tax_rate_id With the books on: the line's account and tax rate. See below.
entries[].pricebook_item_id The Pricebook item the line came from.

Each row of the answer has was_created: false when use found an existing document.

With the books on, every line needs an account

Once an account's books are on, every line with money on it needs an account: send ledger_account_id, or a code that is an account code in the chart. A line without one is refused with a 400 that names the line. There is no default sales account, so nothing is booked to the wrong place unseen. Get account ids from GET /v2/ledger/accounts and tax rate ids from GET /v2/ledger/tax-rates.

A 409 means the books refused to post the invoice for a reason only fixed in the books, such as a missing system account. The message says what to fix. Nothing was saved.

Two kinds of status

In the request, status is the kind of document to make (0 quote, 1 invoice). In every answer, status is the payment code (0 unpaid, 1 paid, 2 part paid, 3 void) and quote_invoice is the kind (0 quote, 1 invoice, 2 credit note). Read payment_status and document_type for the words.

An invoice for 0.00 is paid as soon as it's made. A document coming to less than zero is refused: make a credit note.

Retired fields

Since 9 November 2026, an invoice no longer has payment_method or payment_reference: an invoice paid in two parts was paid two ways. Read them from its payments: GET /v2/payments?invoice_id=….

Change one: POST /v2/clientzone/editInvoice

Only inv_id is required. A field you leave out keeps what's stored: lines, layout, dates, tax mode and Reference. An empty entries list is refused. A save that changes nothing writes nothing and starts nothing.

  • Send updated_at exactly as you read it. If someone saved the document after that, you get a 409 asking you to read it again, instead of overwriting their change.
  • document_date can change only while the document has no money on it. An invoice made from a quote can't be dated before the quote, and a locked period is refused.
  • The answer carries the document's money as it is now: status, amount_paid, amount_credited, balance_due, payment_status and updated_at.

List and export

  • POST /v2/clientzone/getInvoices lists documents. It takes paid_state (all, unpaid, paid, part_paid, overdue, void), sort_by (document_date, number, due_date, total, balance) and sort_dir. Void documents are left out unless you ask for void. Rows carry due_date, is_overdue, days_overdue and client_deleted; the first page also has totals for everything that matches. Rows carry their lines with include_line_items: true, which is the default for an API key; send false to leave them out.
  • POST /v2/clientzone/exportDataInvoices gives the CSV described under Export.

When a call is refused

Call Refused when What to do
editInvoice The invoice has money on it (paid, part paid, credit applied), is reconciled, void, or dated in a locked period; or updated_at is stale (409). Remove its payments or use a credit note; read it again.
voidClientInvoice It has money on it, is reconciled, has live credit notes, or is in a locked period. Remove the payments, void the credit notes first, or credit it instead.
quoteToInvoice The quote is void. Copy it to a new quote.
toggleInvoiceRecon Ticking reconciled while the books are on (409). Clearing still works. Reconcile by matching payments to bank lines in Banking.
Bulk actions Some documents can't be done. Read skipped_documents: each has the number, a reason and a plain message to show.

Payments

The payment routes live under /v2/payments.

Record one: POST /v2/payments

Send the client, the amount, the date and, to pay invoices, the invoices it pays. Methods: ach, wire, cheque (or check), eft (or bank_transfer), cash, card, card_machine, credit, other, or the code of one of the account's own methods (custom_1 …, see Payment methods). A payment's method_label names it as the account named it.

  • Retry safely with Idempotency-Key. Send a header Idempotency-Key (1 to 64 letters, digits and _ . : -) that's unique to this payment. A repeat with the same key records nothing and answers 200 with the payment and was_recorded: false. A new payment answers 201 with was_recorded: true.
  • Dates can't be after today or before 2000. A date more than a year ago, or before the books start, is recorded with a date_warning in the answer.
  • A payment in another currency than the books' is kept as the client's credit, but not posted to the books.

POST /v2/clientzone/toggleInvoicePaid (the Paid tick) also takes deposit_account_id: the bank account the money went into, with the books on.

Payment methods: GET /v2/payments/methods

The account's methods in its order, each with code, label and hidden. Until the account changes any, they are the usual ones for its currency (ACH, Check, Wire transfer … in the US). Every line is alike: a usual one keeps its built-in code (ach, cheque …), one the account added is custom_<n>. A hidden line isn't offered in the CRM, but a payment can still be recorded with it. Add usage=1 for in_use, the number of payments using each. Needs View Invoices.

PUT /v2/payments/methods replaces the list, in the order sent, with Manage Users too. Send the version the GET answered, and every line in methods: an existing one as { code, label, hidden } (renaming it renames it on every payment) and a new one as { label, hidden }. A line left out is deleted; that's refused with a 409 while a payment uses it. If someone changed the list after you read it, you get a 409 too: read it again and reapply your change. At least one line stays switched on; at most 40 lines, each name 1 to 40 characters and unique.

Read them: GET /v2/payments

  • With client_id or invoice_id: that client's or invoice's payments. include_removed=1 shows a client's removed ones too.
  • With neither: the whole account, for keys whose person sees every client. Add updated_since (a date or a date and time) to get only payments recorded or changed since then, each with updated_at: the way to keep another system in step. Page with before_id.

Correct one: PATCH /v2/payments/:id

Changes reference, note, method, and, while the payment isn't matched to a bank line, no invoice it paid is reconciled and neither date is locked, date and deposit_account_id. The answer lists what changed and any date_warning. No automation runs. To change the amount, remove the payment and record it again.

Remove or refund

  • DELETE /v2/payments/:id removes a payment. It needs Refund and remove payments. (Without it, a person with Pay Invoices can remove only a payment they entered by hand in the CRM that same day.) A 403 names the right.
  • POST /v2/payments/refund records credit paid back to a client, and POST /v2/credit-notes/refund/:invoiceId refunds a sale. Both need Refund and remove payments.

Online payments

  • POST /v2/payments/payment-link gives an invoice's payment link. With an amount below the balance, the link asks the client for that amount only, such as a deposit, and they can't change it.
  • POST /v2/payments/charge-card charges a card the client saved, for an invoice. It needs Pay Invoices. Only one charge runs at a time for an invoice (409 while one is running), and an expired card is refused.

Credit notes

The credit note routes live under /v2/credit-notes:

Route Makes
POST /from-invoice/:invoiceId A credit note for all of an invoice, chosen lines, or an amount.
POST /write-off/:invoiceId A write-off of what the invoice still owes.
POST /short-payment/:invoiceId A short payment: the difference when a client paid a little less.
POST / A credit note on its own, for goodwill or an old system's unused credit. Lines as an invoice's.
POST /:id/void Voids one.
GET / Lists them. Without a client, the whole account; updated_since returns only those made or changed since.

The create routes take reference and if_reference_exists (use gives back the client's existing credit note with that Reference, answering 200 with was_created: false) and start_automations: false for old credit notes.

Statements

POST /v2/statements/send emails statements: to the clients you name, or to those who owe (owing) or are overdue (overdue), 25 at a time with a cursor for the next batch. It needs View Invoices and Send Bulk, and reports each client as sent, or why not. GET /v2/statements/:clientId/outstanding and /activity read a statement, and /pdf after either gives its PDF.

Importing your history

To move documents in from another system with the API:

  1. Use a key limited to invoices, payments and the books, with a higher limit.
  2. Set Next number in Settings, or send document_number to keep each old number.
  3. Make each document with document_date, reference, if_reference_exists: "use", expected_total, tax_amount and start_automations: false.
  4. Record each payment with its own date and reference, and an Idempotency-Key built from the old system's payment ID, so a re-run never records it twice.

The whole checklist is in Moving to BaseCloud from another accounting system.