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 in reference. reference is
    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-120 with INV-%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 number for a new invoice. Cybooks numbers it on approval.
  • number is 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} rejects number.
  • An archived draft does not hold its number. Restoring it
    (POST /v1/credit-notes/{id}/restore) is refused with
    credit_note_number_taken when 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 is credit_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

Statuserror.codeWhen
422invoice_number_takenThe 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.
422credit_note_number_takenThe same, for a credit note: the supplied number already belongs to another credit note.
422validation_failednumber is not a string, is longer than 191 characters, or was sent on an update. error.fields.number names the field.
422document_number_unavailableThe 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.
409document_number_conflictAnother 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.

Did this page help you?