Skip to navigation

Keep your users updated as your project evolves

June 24, 2026

A hardening pass over the document API (invoices, quotes, proformas, credit notes). Three breaking changes — the id you pass for the customer, the line-item write field, and how document API-key scopes resolve — plus optional number and bank_account_id on create. Request bodies also become flat (the resource wrapper is deprecated but still accepted) across documents, contacts, and bank accounts.

Breaking: customer_id is a Contact id, not a Party id

When creating or updating a document, customer_id now refers to a Contact — the id returned by GET /workspaces/{workspace_id}/contacts — not a Party. The API resolves it to that contact’s current legal entity and scopes the lookup to your workspace, so an unknown or cross-workspace id is rejected with 422 instead of linking the wrong entity.

If you previously looked up a Party and sent its id, send the contact’s id instead. Create the contact first if you don’t have one — a Party is only an addressable customer through a Contact.

Breaking: line items are sent as line_items

The create/update line-item field is renamed line_items_attributes → line_items, matching the line_items you already receive in responses. This supersedes the June 15 note that introduced line_items_attributes.

- "line_items_attributes": [ { "name": "Consulting", "quantity": "10" } ]
+ "line_items": [ { "name": "Consulting", "quantity": "10" } ]

The per-line id and _destroy markers for editing or removing existing lines are unchanged.

Breaking: document API-key scopes are per-type

An API key scoped to one document type no longer grants the others. A key with read:invoices reads invoices but not quotes, proformas, or credit notes — scope each type the integration needs:

read:invoices read:quotes read:proformas read:credit_notes

The documents scope (e.g. read:documents) still grants all four at once. Re-issue any key that needs cross-type access with the scopes it requires.

New: request bodies are flat (the resource wrapper is deprecated)

Send a resource’s fields at the top level — the same shape you already get back in responses. The legacy { "<resource>": { … } } wrapper is deprecated but still accepted, so existing integrations keep working.

POST /workspaces/{workspace_id}/invoices
- { "document": { "customer_id": 742, "currency": "EUR", "line_items": [ … ] } }
+ { "customer_id": 742, "currency": "EUR", "line_items": [ … ] }

This covers invoices, quotes, proformas, credit notes, contacts, and bank accounts. The MCP tools already take the same flat objects.

New: number and bank_account_id are optional on create

Omit number and the document is numbered from your default number series; omit bank_account_id and your default bank account is used. Set number_series_id and the number is drawn from that series instead of the default. Send either field explicitly to override.

New: leaner bank-account creation

Creating a bank account now needs only name and an identifier — iban or account_number. currency defaults to your workspace’s currency, and swift_code is optional.

Changed: currency is returned uppercase

Currency comes back as the canonical ISO-4217 uppercase code — "EUR", not "eur" — on documents and bank accounts. Inbound values are still accepted in any case.

Fixed: clearer 4xx on bad input

Invalid enum values return 422 with a validation message instead of 500. A bank_account_id, project_id, or document-link id from another workspace is rejected with 422 rather than silently ignored.