quaderno.api.* operation is listed below with parameter shapes and return types from the plugin Zod schemas.
Authorization
authorization
authorization
Which account this key belongs to: identity.href is that account’s base URL, so this is how a caller finds the subdomain to pass as account. Also returns the default API version.
Risk: read
identity full type
identity full type
Contacts
create
contacts.create
Adds a customer. first_name is required, and holds the company name for a company. Give an email if documents will be delivered to this contact.
Risk: write
contact full type
contact full type
delete
contacts.delete
Removes a customer. Quaderno refuses with 422 while the contact still has documents attached, so invoices must be voided first. Answers 204 with no body.
Risk: destructive · Irreversible
get
contacts.get
One customer by id. An unknown id answers 401, not 404, with “Unauthorized access or contact does not exist”; the plugin reports it as not_found_or_denied.
Risk: read
contact full type
contact full type
list
contacts.list
Customers, newest first, answered as a bare array. Search with q and page with created_before; next_created_before carries the next cursor.
Risk: read
contacts full type
contacts full type
update
contacts.update
Changes a customer. Fields left out are left unchanged by the API, not cleared.
Risk: write
contact full type
contact full type
Credits
create
credits.create
Issues a credit note against an existing invoice, by invoice_id, and records the refund. It credits the whole invoice unless credited_amount is given. It consumes a document number and cannot be deleted, only voided.
Risk: write
invoice_id. It credits the full invoice unless credited_amount is set, which only works for an invoice with one line.
Output
credit full type
credit full type
deliver
credits.deliver
Emails the credit note to the address on file for its contact. A GET that mutates, so it is a write and is never replayed. Answers delivered: true.
Risk: write
get
credits.get
One credit note by id, with its lines, payments and the document it credits.
Risk: read
credit full type
credit full type
list
credits.list
Credit notes, newest first, as a bare array. A voided invoice leaves one of these beside it.
Risk: read
credits full type
credits full type
update
credits.update
Changes the administrative fields of a credit note: notes, payment_details and tag_list. Amounts, lines and the customer are immutable once it is issued.
Risk: write
credit full type
credit full type
void
credits.void
Voids a credit note. void_reason is required, exactly as for an invoice.
Risk: destructive · Irreversible
credit full type
credit full type
Invoices
create
invoices.create
Issues an invoice and allocates a document number, which is not recoverable: invoices cannot be deleted, only voided. Passing payment_method records a full payment immediately and marks it paid. Needs a contact id and at least one line item.
Risk: write
payment_method to record a full payment at the same time.
contact full type
contact full type
items full type
items full type
invoice full type
invoice full type
deliver
invoices.deliver
Sends the invoice by email to the address on file for its contact, using the account template. A GET that mutates, so it is a write here and never replayed: delivering twice emails twice. The contact needs a valid email. Answers no document, only delivered: true.
Risk: write
delivered: true; read the invoice again to see its delivery history.
Output
get
invoices.get
One invoice with its lines, taxes and payments. An unknown id answers 401 rather than 404.
Risk: read
invoice full type
invoice full type
list
invoices.list
Invoices, newest first, as a bare array. Filter by date, state, contact or processor id, search with q, and page with created_before.
Risk: read
date takes a range, two ISO dates joined by a comma (2026-01-01,2026-12-31), not a single date.
Output
invoices full type
invoices full type
markUncollectible
invoices.markUncollectible
Marks an unpaid invoice as bad debt. Reversible by recording a payment later, unlike a void.
Risk: write
invoice full type
invoice full type
recordPayment
invoices.recordPayment
Records a payment against an invoice; reaching the total marks it paid. This creates a real financial record, not a note.
Risk: write
payment full type
payment full type
update
invoices.update
Changes an invoice. Only the fields you send are changed. An issued invoice is legally immutable: Quaderno then accepts only notes, payment_details and tag_list, so correct anything else by voiding it and issuing a new one.
Risk: write
contact full type
contact full type
items full type
items full type
invoice full type
invoice full type
void
invoices.void
Reverses an invoice the way tax law requires. It cannot be deleted: voiding records an offset payment for the full amount and issues a credit note beside it. void_reason is required and the API answers 422 without it.
Risk: destructive · Irreversible
void_reason. It does not delete: the invoice stays and a credit note is issued beside it.
Output
invoice full type
invoice full type
Jurisdictions
get
jurisdictions.get
One tax jurisdiction by id, naming the country and any region whose tax rules apply.
Risk: read
jurisdiction full type
jurisdiction full type
list
jurisdictions.list
Every tax jurisdiction Quaderno knows, about 290 rows, as a bare array. Verified live: this route ignores limit and always returns the full list.
Risk: read
jurisdictions full type
jurisdictions full type
Ping
ping
ping
Checks that the key and account name are valid. The docs say it does not consume an API call. Answers {"status":"OK"}.
Risk: read
Products
create
products.create
Adds a product. name, code and unit_cost are required, and kind is one_off or subscription, not the value the spec’s example suggests.
Risk: write
product full type
product full type
delete
products.delete
Removes a product. Existing documents keep the line they were issued with, so past invoices are unaffected.
Risk: destructive · Irreversible
get
products.get
One product by id, with its price, tax class and the currency it is sold in.
Risk: read
product full type
product full type
list
products.list
Your product catalogue, newest first, from the /items route. A bare array; page with created_before.
Risk: read
products full type
products full type
update
products.update
Changes a product. Existing documents keep the line they were issued with, so past invoices are unaffected.
Risk: write
product full type
product full type
Proformas
accept
proformas.accept
Marks a proforma accepted. A state change the customer would normally trigger; reversible with proformas.revert.
Risk: write
proforma full type
proforma full type
convert
proformas.convert
Converts an accepted proforma into a real invoice, which consumes an invoice number and cannot be undone. Only a proforma in the accepted state can be converted. Returns the new invoice under invoice.
Risk: write
invoice.
Output
invoice full type
invoice full type
create
proformas.create
Creates a proforma. Unlike an invoice this is not a tax document, so it does not consume an invoice number.
Risk: write
contact full type
contact full type
items full type
items full type
proforma full type
proforma full type
decline
proformas.decline
Marks a proforma declined. Reversible with proformas.revert.
Risk: write
proforma full type
proforma full type
deliver
proformas.deliver
Emails the proforma to the address on file for its contact. A GET that mutates, so it is a write and is never replayed. Answers delivered: true.
Risk: write
get
proformas.get
One proforma by id, with its lines and the state it was accepted or declined in.
Risk: read
proforma full type
proforma full type
list
proformas.list
Proforma invoices, newest first, as a bare array. A proforma is not a tax document, so it carries no invoice number.
Risk: read
proformas full type
proformas full type
revert
proformas.revert
Puts an accepted or declined proforma back to its open state.
Risk: write
proforma full type
proforma full type
update
proformas.update
Changes a proforma. Only the id is required. An accepted or invoiced proforma cannot be changed. It stays a proforma until proformas.convert issues a real invoice.
Risk: write
contact full type
contact full type
items full type
items full type
proforma full type
proforma full type
Receipts
create
receipts.create
Issues a receipt for a sale that is already paid, so payment_method is required. Like an invoice, it consumes a document number and cannot be deleted or updated, only voided.
Risk: write
payment_method is required: a receipt records a sale that is already paid.
contact full type
contact full type
items full type
items full type
receipt full type
receipt full type
deliver
receipts.deliver
Emails the receipt to the address on file for its contact. A GET that mutates, so it is a write and is never replayed. Answers delivered: true.
Risk: write
get
receipts.get
One receipt by id, with its lines, payments and the invoice it settles.
Risk: read
receipt full type
receipt full type
list
receipts.list
Receipts, newest first, as a bare array. Filter by a date range or contact, and page with created_before.
Risk: read
receipts full type
receipts full type
void
receipts.void
Voids a receipt. void_reason is required, as for an invoice.
Risk: destructive · Irreversible
receipt full type
receipt full type
Tax Codes
get
taxCodes.get
One tax code by its identifier, such as standard.
Risk: read
tax_code full type
tax_code full type
list
taxCodes.list
The tax codes available on the account, as a bare array. This route honours limit, unlike jurisdictions.list.
Risk: read
tax_codes full type
tax_codes full type
Tax Ids
validate
taxIds.validate
Checks a VAT or tax number against the country’s registry. valid is true or false, or null when the registry could not be reached, which does not mean the number is invalid.
Risk: read
Tax Rates
calculate
taxRates.calculate
The tax rate Quaderno would charge for a customer country and tax code, with the resulting total. tax_code and amount are required from API version 20210316, which this plugin targets.
Risk: read
tax_code and amount are required from API version 20210316.
Output
Transactions
create
transactions.create
Records a sale or a refund in one call: it creates the document and its payment together, which is what distinguishes it from invoices.create. The body is not an invoice body: the buyer is customer, each line carries its total as amount, and payment.method is required. A real financial record.
Risk: write
customer, each line carries its total as amount, and payment.method is required.
customer full type
customer full type
items full type
items full type
payment full type
payment full type
transaction full type
transaction full type
Webhooks
list
webhooks.list
The webhook subscriptions on the account, with the events each one receives. Read only here: this plugin registers no inbound handler. The signing secret (auth_key) is left out of the result.
Risk: read
auth_key) is left out of each row.
Output
webhooks full type
webhooks full type