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_atexactly 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_datecan 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_statusandupdated_at.
List and export¶
POST /v2/clientzone/getInvoiceslists documents. It takespaid_state(all,unpaid,paid,part_paid,overdue,void),sort_by(document_date,number,due_date,total,balance) andsort_dir. Void documents are left out unless you ask forvoid. Rows carrydue_date,is_overdue,days_overdueandclient_deleted; the first page also hastotalsfor everything that matches. Rows carry their lines withinclude_line_items: true, which is the default for an API key; sendfalseto leave them out.POST /v2/clientzone/exportDataInvoicesgives 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 headerIdempotency-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 andwas_recorded: false. A new payment answers 201 withwas_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_warningin 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_idorinvoice_id: that client's or invoice's payments.include_removed=1shows 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 withupdated_at: the way to keep another system in step. Page withbefore_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/:idremoves 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/refundrecords credit paid back to a client, andPOST /v2/credit-notes/refund/:invoiceIdrefunds a sale. Both need Refund and remove payments.
Online payments¶
POST /v2/payments/payment-linkgives an invoice's payment link. With anamountbelow 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-cardcharges 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:
- Use a key limited to invoices, payments and the books, with a higher limit.
- Set Next number in Settings, or send
document_numberto keep each old number. - Make each document with
document_date,reference,if_reference_exists: "use",expected_total,tax_amountandstart_automations: false. - Record each payment with its own date and reference, and an
Idempotency-Keybuilt 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.