Invoices
Invoices
A sales invoice starts as a draft (POST /v1/invoices,
cybooks_create_invoice over MCP). A draft posts nothing. Approving it
(POST /v1/invoices/{id}/approve, cybooks_approve_invoice) gives it its
number, posts it to the ledger and makes it due. How numbers are assigned is
in Invoice numbering.
The account on each line
Every line posts its amount to an income account, such as Sales. Name it
on the line in one of two ways:
| Field | What it is |
|---|---|
account_id | The account's id from the chart of accounts list (GET /v1/accounting/chart-of-accounts, cybooks_list_chart_of_accounts). Every account has one. |
account_code | The account's code, such as 4000. |
Codes are optional in a chart of accounts: a chart imported or built without
them has "code": null on its accounts, and then only account_id can name
the account. Send account_id whenever you have it.
POST /v1/invoices
{
"contact_id": "…",
"date_of_invoice": "2026-03-31",
"currency_id": "…",
"tax_type": "net",
"line_items": [
{
"type": "line_item",
"description": "Consulting, March 2026",
"quantity": 1,
"net_unit_price": 1200.00,
"account_id": "4012",
"tax_code": "L",
"order": 0
}
]
}account_idmust name an active income account of the company (not
archived, and not an account type or detail type heading). Anything else is
refused withinvoice_line_account_unavailable, naming the line. The id is
a string of digits, as the chart of accounts list returns it (over REST a
JSON number is accepted too).- If you send both
account_idandaccount_code, they must name the same
account. account_codekeeps working as before.- When you leave out the tax code, the line takes the account's default tax
rule. - The invoice you get back shows each line's account as
chart_of_account_id
(the same id) andaccount_code.
A line without an account
You can save a draft with a line that has no account, for example to finish it
in Cybooks later. It cannot be approved that way. Approval refuses it with
422 invoice_line_account_missing and posts nothing. The invoice stays a
draft.
{
"error": {
"type": "validation_error",
"code": "invoice_line_account_missing",
"message": "invoice_line_account_missing: Line 1 of this draft has no account, so the invoice cannot post. …",
"fields": {
"line_items.0.account_id": ["This line needs an income account before the invoice can be approved."]
}
}
}error.fields names every line without an account, numbered from 0 in the
order GET /v1/invoices/{id} lists the lines. A free-text line and a discount
line need no account.
To fix it, update the draft (PUT /v1/invoices/{id} with the invoice's
Cybooks-If-Match (or the standard If-Match) ETag, cybooks_update_invoice over MCP) and approve again. The
line_items you send replace the draft's lines, so send every line, each
with its id and its account:
- a line that already has an account: send its
chart_of_account_idfrom
GET /v1/invoices/{id}asaccount_id(or itsaccount_code). A line sent
without an account is saved without one, whatever it had before; - the line that had none: the
account_idof the income account it belongs
to.
Cybooks does not choose an account for you. The app does not either: its
invoice editor fills in the Sales account on every new line, so a line never
reaches approval without one.
Credit notes
A credit note's lines name their account the same way: account_id or
account_code on each line of POST /v1/credit-notes and
PATCH /v1/credit-notes/{id} (cybooks_create_credit_note,
cybooks_update_credit_note over MCP). Use the income account the original
invoice line posted to, so the credit reverses it: approving the credit note
debits that account.
POST /v1/credit-notes
{
"contact_id": "…",
"date_of_credit_note": "2026-03-31",
"currency_id": "…",
"tax_type": "net",
"line_items": [
{
"type": "line_item",
"description": "Storno: returned item",
"quantity": 1,
"net_unit_price": 29.25,
"account_id": "4012",
"tax_code": "L",
"order": 0
}
]
}- Every line item and surcharge needs
account_idoraccount_code; a line
with neither is refused when you create or update the draft
(invalid_request, online_items.N.account_code). A free-text line and a
discount line need none. account_idfollows the invoice rule: an active income account of the
company, refused otherwise withcredit_note_line_account_unavailable,
naming the line. Withaccount_codetoo, both must name the same account.- Approving (
POST /v1/credit-notes/{id}/approve,
cybooks_approve_credit_note) refuses a draft with a line that has no
account with422 credit_note_line_account_missing, shaped like
invoice_line_account_missingabove, and posts nothing. A draft made in
Cybooks, or copied from an opening-balance invoice, can have one. Fix it with
PATCH /v1/credit-notes/{id}: theline_itemsyou send replace the draft's
lines, so send every line with itsidand its account.
The tax rule on a credit-note line
Name a line's tax rule by tax_code, or by tax_rule_id (the id from
GET /v1/accounting/tax-rules, cybooks_list_tax_rules over MCP). Use the id
when the rule has no code: a tax rule made in Cybooks has none. Send neither
and the line takes its account's default tax rule.
tax_rule_idmust name a sales or no-VAT tax rule of the company. Anything
else (a purchase rule, a deleted rule, an id the company does not have) is
refused with one answer,422 credit_note_line_tax_rule_unavailableon
line_items.N.tax_rule_id.- Send both and they must name the same rule, else
422 credit_note_line_tax_rule_mismatch. - The rate is always the rule's own.
tax_rateis never accepted. - A credit note line's response carries
tax_rule_idandtax_code; resend
thetax_rule_idto keep a rule without a code when you replace the lines.
A line whose rule is not a sales or no-VAT rule (one set bytax_code)
keeps it only by itstax_code: resend that alone.
A credit note you already issued elsewhere
Send its original number in number on create, never in reference:
approval keeps it. See Invoice numbering.
Attachments
GET /v1/invoices/{id}/attachments lists the files attached to an invoice,
each with a download_url that works for five minutes (expires_at) and needs
no Authorization header; invoices have no single attachment read. Credit
notes list theirs with GET /v1/credit-notes/{id}/attachments and read one,
link and optional content_base64 included, with
GET /v1/credit-notes/{id}/attachments/{attachmentId}?include_content=true
(see Bills, "Read the supplier's file").
Who gets the email
POST /v1/invoices/{id}/send (cybooks_send_invoice), /resend and /remind
(cybooks_remind_invoice) send to receiver and can copy other people. The
credit note, quote and receipt sends take the same fields.
| Field | What it does |
|---|---|
receiver | Who the email goes to (up to 20 addresses). |
cc | Addresses to copy (up to 20). Omit it and the email copies the customer's saved cc_emails. Send [] for no copies. Send a list and exactly that list is copied. |
bcc | Addresses to blind-copy (up to 20). Cybooks never fills it in: only what you send is blind-copied. |
The customer's cc_emails is a list of up to 5 addresses you read and write on
/v1/customers (omit it to leave it as it is, send [] or null to clear it).
A customer with no saved copies reads cc_emails: [].
Behaviour change for existing integrations. From November 2026, a send
withoutcccopies the customer's saved copies. Sendcc: []to send to
receiveronly (/remindalso acceptscc: nullfor no copies, while the sends take[]). The operation'srecipientslists everyone the email went to.
The customer saved ["[email protected]"]:
| You send | The email is copied to |
|---|---|
no cc key | [email protected] |
"cc": [] | nobody, receiver only |
"cc": ["[email protected]"] | [email protected] only |
- An address already in
receiveris dropped fromcc, and one inreceiver
orccis dropped frombcc(compared ignoring case). - To, Cc and Bcc together may not pass 50 addresses after those repeats are
removed. A longer list is refused with a 422 onreceiver. - The copies are chosen when the email is queued and kept with it. The
operation'srecipientslists everyone who gets the email. - "Send me a copy" is a separate email to you and never carries copies.
Error codes
| Code | Status | When |
|---|---|---|
invoice_line_account_unavailable | 422 | A line's account_id is not an active income account of this company, or account_id and account_code name different accounts. Returned on create and update. error.fields names the line. |
invoice_line_account_missing | 422 | Approving a draft with a line that has no account. error.fields names each line. |
credit_note_line_account_unavailable | 422 | The same as invoice_line_account_unavailable, for a credit-note line. |
credit_note_line_account_missing | 422 | Approving a draft credit note with a line that has no account. error.fields names each line. |
credit_note_line_tax_rule_unavailable | 422 | A credit-note line's tax_rule_id is not a sales or no-VAT tax rule of this company. error.fields names the line. |
credit_note_line_tax_rule_mismatch | 422 | A credit-note line's tax_rule_id and tax_code name different tax rules. Send one of them. |
invoice_number_taken, credit_note_number_taken | 422 | See Invoice numbering. |
adjustment_discount_type_unsupported | 422 | A discount or surcharge row has a discount_type other than percent. A document discount or surcharge is a percentage of the lines above it; use percent, or put the amount on a line item. error.fields names the row. |
adjustment_unit_price_not_accepted | 422 | A discount or surcharge row carries a net_unit_price or gross_unit_price that is not the amount the server computes from its percentage. Send 0 as the unit price and the percentage in discount; the row's amount is in the response. 0 and the computed amount are accepted. |
List filters
Use filter[date_from] and filter[date_to] for inclusive invoice dates (YYYY-MM-DD), and filter[tax_rule_id] for invoices with any line using that rule. filter[search] matches the whole phrase in the invoice number, reference, customer snapshot or line description. %, _ and backslash are literal; a blank search is refused. Combine these with the existing id, status and contact filters. MCP takes them in query.filter.
Updated 8 days ago
