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:

FieldWhat it is
account_idThe 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_codeThe 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_id must name an active income account of the company (not
    archived, and not an account type or detail type heading). Anything else is
    refused with invoice_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_id and account_code, they must name the same
    account.
  • account_code keeps 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) and account_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_id from
    GET /v1/invoices/{id} as account_id (or its account_code). A line sent
    without an account is saved without one, whatever it had before;
  • the line that had none: the account_id of 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_id or account_code; a line
    with neither is refused when you create or update the draft
    (invalid_request, on line_items.N.account_code). A free-text line and a
    discount line need none.
  • account_id follows the invoice rule: an active income account of the
    company, refused otherwise with credit_note_line_account_unavailable,
    naming the line. With account_code too, 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 with 422 credit_note_line_account_missing, shaped like
    invoice_line_account_missing above, 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}: the line_items you send replace the draft's
    lines, so send every line with its id and 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_id must 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_unavailable on
    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_rate is never accepted.
  • A credit note line's response carries tax_rule_id and tax_code; resend
    the tax_rule_id to 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 by tax_code)
    keeps it only by its tax_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.

FieldWhat it does
receiverWho the email goes to (up to 20 addresses).
ccAddresses 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.
bccAddresses 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
without cc copies the customer's saved copies. Send cc: [] to send to
receiver only (/remind also accepts cc: null for no copies, while the sends take []). The operation's recipients lists everyone the email went to.

The customer saved ["[email protected]"]:

You sendThe email is copied to
no cc key[email protected]
"cc": []nobody, receiver only
"cc": ["[email protected]"][email protected] only
  • An address already in receiver is dropped from cc, and one in receiver
    or cc is dropped from bcc (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 on receiver.
  • The copies are chosen when the email is queued and kept with it. The
    operation's recipients lists everyone who gets the email.
  • "Send me a copy" is a separate email to you and never carries copies.

Error codes

CodeStatusWhen
invoice_line_account_unavailable422A 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_missing422Approving a draft with a line that has no account. error.fields names each line.
credit_note_line_account_unavailable422The same as invoice_line_account_unavailable, for a credit-note line.
credit_note_line_account_missing422Approving a draft credit note with a line that has no account. error.fields names each line.
credit_note_line_tax_rule_unavailable422A 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_mismatch422A credit-note line's tax_rule_id and tax_code name different tax rules. Send one of them.
invoice_number_taken, credit_note_number_taken422See Invoice numbering.
adjustment_discount_type_unsupported422A 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_accepted422A 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.


Did this page help you?