Invoice numbering
Invoice numbering
Every sales invoice, credit note and vendor credit takes its number from the
company's number sequence (Settings → Sequences, for example
INV-%NUMBER). The number is assigned when the document is approved, not
when it is created.
Drafts
A draft's number is provisional. It shows the number the next approval would
take, so several drafts can show the same number, and creating a draft reserves
nothing.
When you approve a draft (POST /v1/invoices/{id}/approve, or
cybooks_approve_invoice over MCP), Cybooks assigns the next number in the
sequence and moves the sequence on by one. Two drafts approved one after the
other get two consecutive numbers, whichever order they were created in. The
same applies to credit notes and vendor credits.
If the next sequence number already belongs to an invoice — a migrated invoice
you supplied it for, say — approval skips it and takes the next free one.
Read the final number from the approval response, or from the invoice once it
is approved. Do not store a draft's number as the document's number.
Invoices you already issued elsewhere
When you move invoices from another system into Cybooks, they already have
numbers your customers have seen. Send each one's original number in number
when you create it:
POST /v1/invoices
{
"number": "INV-000017",
"contact_id": "…",
"date_of_invoice": "2026-03-14",
"currency_id": "…",
"tax_type": "net",
"line_items": [ … ]
}- Put the original number in
number, never inreference.referenceis
your own free text, such as a purchase order number, and approval does not
read it. - Approval keeps a number you supplied. It does not take a number from the
sequence. - If the number fits the sequence's format (
INV-120withINV-%NUMBER),
approving the invoice moves the sequence past it, so new invoices never repeat
it. A number in any other format (2023/0005) leaves the sequence alone. - A draft with a supplied number does not move the sequence until you approve
it, but no other invoice can take its number in the meantime: approval skips
a number a supplied draft holds. - Omit
numberfor a new invoice. Cybooks numbers it on approval. numberis set when the invoice is created and cannot be changed afterwards.
PUT /v1/invoices/{id}rejects it.- The number becomes part of the stored PDF's file key, so a
.or..path
segment (a backslash counts as a slash) or a control or invisible character
is refused./and\themselves are allowed. - Sales invoices and credit notes accept
number(see below). Estimates,
vendor credits and repeating invoices are always numbered from their sequence.
Over MCP, pass the number in the number field of cybooks_create_invoice.
Credit notes you already issued elsewhere
A credit note migrated from another system keeps its number the same way:
send it in number on POST /v1/credit-notes (cybooks_create_credit_note
over MCP), never in reference. Every rule above applies, with the credit-note
sequence (Settings → Sequences, for example CN-%NUMBER) in place of the
invoice one:
- Approval (
POST /v1/credit-notes/{id}/approve,cybooks_approve_credit_note)
keeps the number and does not take one from the sequence; a number that fits
the sequence's format moves the sequence past it. - A new credit note's approval skips a number a supplied credit-note draft
holds. PATCH /v1/credit-notes/{id}rejectsnumber.- An archived draft does not hold its number. Restoring it
(POST /v1/credit-notes/{id}/restore) is refused with
credit_note_number_takenwhen another credit note took the number
meanwhile; the draft stays archived. - A supplied number must not already belong to another credit note (an issued
one, voided included, or a draft whose number was supplied). Invoices and
credit notes are numbered apart: an invoice's number does not block a credit
note's. The refusal iscredit_note_number_taken, on create, on approve and
on restore.
Duplicate numbers
A supplied number must not already belong to another invoice (for a credit
note: another credit note). Numbers are
compared without surrounding spaces and ignoring case, so inv-17 matches
INV-17. Every approved invoice counts, including voided ones, and so does a
draft whose number was supplied. An ordinary draft's provisional number does
not count.
The check runs when you create the invoice, and again when you approve it, in
case another invoice took the number in between.
Errors
| Status | error.code | When |
|---|---|---|
| 422 | invoice_number_taken | The supplied number already belongs to another invoice. Returned on create, or on approve if the number was taken after the draft was created. error.fields.number names the field. |
| 422 | credit_note_number_taken | The same, for a credit note: the supplied number already belongs to another credit note. |
| 422 | validation_failed | number is not a string, is longer than 191 characters, or was sent on an update. error.fields.number names the field. |
| 422 | document_number_unavailable | The company's sequence cannot issue a number: its format has no %NUMBER, or every number within reach is already taken. Retrying does not help; fix the sequence in Settings → Sequences, then approve again. |
| 409 | document_number_conflict | Another document took the same number at the same moment. Over REST, error.retryable is true and resending the request (with the same Idempotency-Key) can succeed. MCP reports every 409 with retryable: false; an agent may still call the tool once more. |
Updated 25 days ago
