Invoices
Requires scope merchant-invoices-read.
Lists the store’s invoices, newest first, with cursor pagination (limit + starting_after, has_more/next_cursor). Needs the Invoices app installed on the store (403 app_not_installed otherwise). Every row is the object GET invoices/{invoice} answers: number (null on a draft), kind (invoice, proforma or credit_note), status (overdue is derived: issued, past its due date, balance left; refunded is an order-backed invoice whose order was paid, then refunded in full; an enum value added under v1, so tolerate values you do not know), amount_paid (the NET: received less refunded, never below zero or above the total), amount_received (the gross that came in) and amount_refunded (what went back to the customer), source (standalone, or order for an invoice that mirrors an order’s payments and balance, with that order), the buyer, the lines, the totals, payments, installments and credit_notes. Every id is a p_id, every amount a decimal string at the invoice’s currency precision beside its ISO currency. Filters: status, kind, customer_id and order_id (a p_id or UUID of this store; one that is not this store’s lists nothing), q (number, title or buyer name or phone; needs merchant-customers-contact-read, 403 insufficient_scope without it), from and to (creation dates, Y-m-d) and updated_since (RFC 3339 with an explicit offset: keeps rows changed at or after that time). The buyer’s name, email and phone are null without merchant-customers-contact-read; the address and tax id are on the document either way. An order-backed invoice (source order) follows its order only when it is read: the updated_since and status filters run on the stored row, so they do not see an order payment until the invoice is read (a row can list under its old status and a stale updated_at); watch the orders/* webhooks or read GET orders/{order}/invoice instead, and note that reading refreshes it and moves its updated_at. The customer link, the order’s pay link, customer payment notices and the merchant’s bank details are never in the object. The window moves as rows change, so a walk through pages is not a snapshot: poll with updated_since for invoices the merchant makes and deduplicate on id and updated_at.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
overdue is a derived state (issued, past due, balance left), filterable like a stored one.
Value in
- "draft"
- "pending"
- "partial"
- "paid"
- "overdue"
- "void"
- "refunded"
- "expired"
- "issued"
- null
invoice, proforma (not a tax invoice) or credit_note.
Value in
- "invoice"
- "proforma"
- "credit_note"
- null
Number, title or buyer name/phone. On the Merchant API it needs merchant-customers-contact-read (403 without it).
length <= 64Only the invoices addressed to this store customer.
^(?:[1-9][0-9]{0,17}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$Only the invoice of this order.
^(?:[1-9][0-9]{0,17}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$First creation day to include (YYYY-MM-DD).
dateLast creation day to include (YYYY-MM-DD), on or after from.
dateOnly items last changed at or after this RFC 3339 timestamp with an explicit offset, for example 2026-10-14T09:30:00+01:00. Poll with it and deduplicate on id plus updated_at.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/invoices?limit=2&status=pending&kind=invoice&updated_since=2026-09-24T09%3A00%3A00%2B01%3A00" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "id": 1042, "number": "INV-000042", "kind": "invoice", "status": "partial", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "180.00", "amount_received": "180.00", "amount_refunded": "0.00", "amount_due": "179.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [ { "id": 2001, "source": "invoice", "kind": "payment", "amount": "180.00", "method": "bank_transfer", "is_cash": true, "reference": "WIRE-2210-8841", "paid_at": "2026-09-24T11:05:00+01:00", "voided_at": null, "void_reason": null } ], "installments": [ { "sequence_no": 1, "expected_amount": "180.00", "paid_amount": "180.00", "status": "paid", "due_at": "2026-09-26", "paid_at": "2026-09-24T11:05:00+01:00" }, { "sequence_no": 2, "expected_amount": "179.64", "paid_amount": "0.00", "status": "pending", "due_at": "2026-10-10", "paid_at": null } ], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T11:05:00+01:00" } ], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wOS0yNCAwOTo0MDowMCIsImlkIjoiMDE5YTViMTAtMmMzZC03ZTRmLThhNWItNmM3ZDhlOWYwYTAxIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-invoices-create.
Creates a DRAFT invoice (or a proforma, which is not a tax invoice): it has no number yet and is not shown to the customer until it is issued with POST invoices/{invoice}/issue. You send only what a person would type: lines (description, quantity, unit_price and optionally tax_rate, tax_name or several named taxes), the buyer (name, email, phone, address, tax_id) or a customer_id (a p_id or UUID of one of this store’s customers, whose details fill the buyer), an invoice-level discount (type fixed or percent, value), due_at, terms, note, title, language (en, fr or ar) and an installments plan. The server computes every total: the subtotal, discount, tax and total are never accepted, and a total_amount, line total or tax amount you send is ignored. Money is a decimal string in the invoice’s currency (the store’s currency unless you send a supported currency), with no more decimals than that currency has (more answers 422). Answers 201 with the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). A draft is not a document yet: it takes no payment and consumes no invoice number. Fires invoices/create. Send an Idempotency-Key so a retried call does not create a second draft.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Create a draft invoice (or proforma). Only what the merchant types is accepted; the server computes subtotal, discount, tax and total and ignores anything else sent.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "title": "Wedding catering, 12 October", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006" }, "lines": [ { "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8" } ], "discount": { "type": "percent", "value": "10" }, "due_at": "2026-10-10", "terms": "Balance due before the event." }'{ "status": "success", "message": "Invoice draft created.", "data": { "id": 1044, "number": null, "kind": "invoice", "status": "draft", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": null }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": null, "address": null, "registration_number": null, "tax_id": null, "tax_id_label": null }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": null, "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T09:40:00+01:00" }}Requires scope merchant-invoices-read.
Retrieves one invoice with its lines, tax breakdown, payments, instalments and credit notes. {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). Needs the Invoices app installed on the store (403 app_not_installed otherwise). Money is a decimal string beside the invoice’s ISO currency; the buyer’s name, email and phone are null without merchant-customers-contact-read. An order-backed invoice (source order) is brought in line with its order first and lists the order’s payments and refunds with source order. The customer link, the order’s pay link, customer payment notices and the merchant’s bank details are never in the object.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/invoices/1042" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Invoice retrieved.", "data": { "id": 1042, "number": "INV-000042", "kind": "invoice", "status": "partial", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "180.00", "amount_received": "180.00", "amount_refunded": "0.00", "amount_due": "179.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [ { "id": 2001, "source": "invoice", "kind": "payment", "amount": "180.00", "method": "bank_transfer", "is_cash": true, "reference": "WIRE-2210-8841", "paid_at": "2026-09-24T11:05:00+01:00", "voided_at": null, "void_reason": null } ], "installments": [ { "sequence_no": 1, "expected_amount": "180.00", "paid_amount": "180.00", "status": "paid", "due_at": "2026-09-26", "paid_at": "2026-09-24T11:05:00+01:00" }, { "sequence_no": 2, "expected_amount": "179.64", "paid_amount": "0.00", "status": "pending", "due_at": "2026-10-10", "paid_at": null } ], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T11:05:00+01:00" }}Requires scope merchant-invoices-update.
Edits a DRAFT: send only the fields to change, with the same meaning and limits as POST invoices (kind, currency, customer_id, buyer, title, due_at, terms, note, language, discount, installments and lines). Sending lines replaces every line, and the server recomputes the totals from the lines, discount and currency whenever one of them is sent: a total you send is never accepted. The buyer fields you send are merged onto the stored buyer and the ones you leave out stay (a field sent as null is cleared), so a key that reads the buyer’s name, email and phone as null can change the address or tax_id without erasing them. An issued invoice is frozen: only due_at can still move (a deadline extension changes no amount), and any other field the endpoint takes (title, buyer, lines and the rest above) answers 409 invoice_locked. A void invoice, a credit note and an order-backed invoice (source order, which follows its order) answer 409 invoice_locked to every field, due_at included. A field the endpoint does not take (such as total_amount, number or status) is ignored, and a body that changes nothing answers 200 with the invoice as it is (an issued invoice keeps its due date unless due_at is sent) and still fires invoices/update. {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). Answers the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/update. A key holding only merchant-invoices-create cannot edit a draft, not even its own: editing is this scope’s job.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Edit an invoice. A draft takes any field; an issued invoice is immutable and takes
only a new due_at: any other field is refused with invoice_locked.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/invoices/1044" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "terms": "Balance due five days before the event.", "due_at": "2026-10-05" }'{ "status": "success", "message": "Invoice updated.", "data": { "id": 1044, "number": null, "kind": "invoice", "status": "draft", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": null }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": null, "address": null, "registration_number": null, "tax_id": null, "tax_id_label": null }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due five days before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": null, "due_at": "2026-10-05", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T09:45:00+01:00" }}Requires scope merchant-invoices-delete.
Deletes a DRAFT, which has no number and was never shown to the customer. An issued invoice, a void invoice and a credit note are documents and are never deleted: an issued invoice answers 409 invoice_locked (void it with POST invoices/{invoice}/void, or credit it). {invoice} is a p_id or UUID of this store; another store’s invoice, or a draft already deleted, reads like one that does not exist (404). Answers the deleted id (the p_id the invoice read answered) with deleted: true. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/delete, which carries the id alone.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/invoices/1044" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Invoice draft deleted.", "data": { "id": 1044, "deleted": true }}Requires scope merchant-invoices-read.
Retrieves the invoice raised for an order of this store, the same object GET invoices/{invoice} answers. {order} is a p_id or UUID of this store; 404 when the order is not this store’s or has no invoice yet. Needs the Invoices app installed on the store (403 app_not_installed otherwise).
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the order, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/orders/58213/invoice" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Invoice retrieved.", "data": { "id": 1043, "number": "INV-000043", "kind": "invoice", "status": "paid", "credited": false, "source": "order", "order": { "id": 58213, "order_number": "26-0924-58213" }, "corrects_invoice": null, "customer": { "id": 90341 }, "title": null, "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "2", "unit_price": "37.00", "tax_name": null, "tax_rate": "0.00", "taxes": [], "line_total": "74.00", "discount_amount": "7.40", "tax_amount": "0.00" } ], "subtotal": "71.60", "discount": { "type": null, "value": null, "total": "0.00" }, "tax_total": "0.00", "taxes_included": false, "tax_breakdown": [], "total_amount": "71.60", "amount_paid": "71.60", "amount_received": "71.60", "amount_refunded": "0.00", "amount_due": "0.00", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": null, "paid_at": "2026-09-24T13:41:00+01:00", "voided_at": null, "void_reason": null, "created_at": "2026-09-24T14:00:00+01:00", "updated_at": "2026-09-24T14:00:00+01:00" }}Requires scope merchant-invoices-create.
Raises the invoice of an order in one call: an ISSUED, numbered document (it takes the store’s next invoice number and is frozen at once, under merchant-invoices-create alone: there is no separate issue step) over the order’s own items and charges, whose total is exactly what the order charges. An order has one invoice, so the call is repeatable: 201 when this call made it, 200 with the same invoice when the order already had one. The invoice mirrors the order: its paid amount, balance and payments are the order’s own and follow it when it is read (take a payment on the order, not here). {order} is a p_id or UUID of this store; an order that is not this store’s, or a checkout that has not been placed, reads like one that does not exist (404). An order charged in a market’s currency has no invoice: 422 invoice_market_order_unsupported, on the first call and on a repeat. A cancelled or rejected order, or one with no items, answers 409 invoice_state_conflict. Answers the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/create when it makes the invoice.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the order, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/orders/58213/invoice" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Invoice of the order.", "data": { "id": 1043, "number": "INV-000043", "kind": "invoice", "status": "paid", "credited": false, "source": "order", "order": { "id": 58213, "order_number": "26-0924-58213" }, "corrects_invoice": null, "customer": { "id": 90341 }, "title": null, "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "2", "unit_price": "37.00", "tax_name": null, "tax_rate": "0.00", "taxes": [], "line_total": "74.00", "discount_amount": "7.40", "tax_amount": "0.00" } ], "subtotal": "71.60", "discount": { "type": null, "value": null, "total": "0.00" }, "tax_total": "0.00", "taxes_included": false, "tax_breakdown": [], "total_amount": "71.60", "amount_paid": "71.60", "amount_received": "71.60", "amount_refunded": "0.00", "amount_due": "0.00", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": null, "paid_at": "2026-09-24T13:41:00+01:00", "voided_at": null, "void_reason": null, "created_at": "2026-09-24T14:00:00+01:00", "updated_at": "2026-09-24T14:00:00+01:00" }}Requires scope merchant-invoices-update.
Issues a draft: it takes the store’s next invoice number (the numbers are sequential with no gaps, so a refused call uses none), freezes the document (the seller and the totals are fixed, and it can no longer be edited, only voided and replaced) and becomes payable. due_at may set the due date in the same call. {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). A draft needs a buyer name, at least one line, a total above zero and, when the merchant’s Invoices settings require it, the buyer’s tax_id: otherwise 409 invoice_state_conflict; an invoice that is already issued answers 409 too, so a retry never takes a second number. Answers the issued invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/update. Send an Idempotency-Key so a retried call replays the first answer.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Issue a draft: allocates its number and freezes it. May set the due date in the same step.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1044/issue" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "due_at": "2026-10-10" }'{ "status": "success", "message": "Invoice issued.", "data": { "id": 1044, "number": "INV-000044", "kind": "invoice", "status": "pending", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T09:50:00+01:00" }}Requires scope merchant-invoices-record-payment.
Records money the merchant confirmed receiving against an issued invoice: a bank transfer, cash, a card terminal, mobile money, or tax withheld at source (method: bank_transfer, cash, pos, mobile_money, other or tax_withheld). Nothing moves through Queek: it settles the document only, and never reaches the store’s wallet or payouts. amount is a decimal string in the invoice’s currency with no more decimals than it has, above zero and not above the balance (amount_due): a larger one answers 409 invoice_state_conflict. The invoice’s amount_paid, amount_due, status and instalments follow the payments. A draft, a void invoice, one already paid in full, a proforma, a credit note, a credited invoice and an order-backed invoice (source order: its payments are the order’s own) answer 409. paid_at may not be in the future; reference is the payer’s or the bank’s reference. Idempotency-Key is required (400 idempotency_key_required without it): the same key replays the first answer without recording a second payment, and the same key with another amount, method, date or reference answers 409 idempotency_key_reuse, however long ago the first call was. A key is yours alone: another key or installation sending the same string records its own payment. {invoice} is a p_id or UUID of this store. Answers 201 with the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/update.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Record money the merchant confirmed receiving. The amount is validated in the invoice's own currency and precision; the date cannot be in the future. On the Merchant API the Idempotency-Key is required (a retried call would otherwise record the money twice), checked with the permission, before validation; the dashboard's own key stays optional.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1042/payments" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "amount": "180.00", "method": "bank_transfer", "reference": "WIRE-2210-8841", "paid_at": "2026-09-24T11:05:00+01:00" }'{ "status": "success", "message": "Payment recorded.", "data": { "id": 1042, "number": "INV-000042", "kind": "invoice", "status": "partial", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "180.00", "amount_received": "180.00", "amount_refunded": "0.00", "amount_due": "179.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [ { "id": 2001, "source": "invoice", "kind": "payment", "amount": "180.00", "method": "bank_transfer", "is_cash": true, "reference": "WIRE-2210-8841", "paid_at": "2026-09-24T11:05:00+01:00", "voided_at": null, "void_reason": null } ], "installments": [ { "sequence_no": 1, "expected_amount": "180.00", "paid_amount": "180.00", "status": "paid", "due_at": "2026-09-26", "paid_at": "2026-09-24T11:05:00+01:00" }, { "sequence_no": 2, "expected_amount": "179.64", "paid_amount": "0.00", "status": "pending", "due_at": "2026-10-10", "paid_at": null } ], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T11:05:00+01:00" }}Requires scope merchant-invoices-void.
Voids an issued invoice: it keeps its number, stops being payable, and its status becomes void with your reason kept as void_reason. The number stays used (the numbers have no gaps) and a void invoice cannot be edited, paid or credited. 409 invoice_state_conflict for a draft (delete it instead), an invoice that is already void, a credit note (it is the correction), an invoice that already has a credit note (it is already corrected, so it is never reversed twice), an invoice that carries a tax authority reference (correct it with a credit note), an invoice with recorded payments (void each one first with POST invoices/{invoice}/payments/{payment}/void) and an order-backed invoice (source order) whose order took a payment (credit it instead). {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). reason is required (3 to 255 characters). Answers the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/update. A repeat answers 409 and changes nothing; send an Idempotency-Key so a retried call replays the first answer instead.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Void an issued invoice. A reason is required: it is the audit trail of why a number was cancelled.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1044/void" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "reason": "Issued to the wrong customer." }'{ "status": "success", "message": "Invoice voided.", "data": { "id": 1044, "number": "INV-000044", "kind": "invoice", "status": "void", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": "2026-09-24T10:30:00+01:00", "void_reason": "Issued to the wrong customer.", "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T10:30:00+01:00" }}Requires scope merchant-invoices-void.
Issues a credit note for the WHOLE invoice: the correcting document, numbered in the store’s credit-note series (the next number, with no gaps), frozen at once and never payable or voidable. Send only a reason (3 to 500 characters, printed on the note); a body that names amount, lines or any part of the invoice answers 422, because part credit notes are not supported. The invoice itself is not changed: it stays the record of what was issued, reads credited: true (nothing is owed; its amount_due is left as it was) and lists the note in credit_notes (its id, number, total_amount and issued_at); read the note itself with GET invoices/{its id}, where corrects_invoice points back. It records the correction only: it moves no money and does not void or refund a payment. Only an issued invoice (pending, partial, paid or refunded, not void) can be credited, once: a draft, a void invoice, a proforma, a credit note and an invoice that already has a credit note answer 409 invoice_state_conflict, so a repeat issues no second note. Every invoice_state_conflict carries error.reason, a stable sub-code for its cause (for example already_void, already_credited, fiscalised, has_payments, order_took_payment, payment_exceeds_balance). {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). Answers 201 with the corrected invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). Fires invoices/create for the note and invoices/update for the invoice. Send an Idempotency-Key so a retried call replays the first answer.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A credit note against an issued invoice: a correction, so it needs the void permission and a reason. It credits the WHOLE invoice: a body that names amounts or lines is refused (422) instead of being silently credited in full.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1044/credit-notes" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "reason": "Event cancelled by the customer." }'{ "status": "success", "message": "Credit note issued.", "data": { "id": 1044, "number": "INV-000044", "kind": "invoice", "status": "pending", "credited": true, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [ { "id": 1046, "number": "CN-000001", "total_amount": "359.64", "issued_at": "2026-09-24T10:35:00+01:00" } ], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T10:35:00+01:00" }}Requires scope merchant-invoices-fiscal-reference.
Records the reference a tax authority gave an issued invoice (an e-invoicing service or the merchant’s own system returned it), so the document carries it. Send reference (up to 190 characters, trimmed) and optionally meta, up to 20 string values of up to 500 characters each (for example the QR text or a timestamp the authority returned); meta is stored for the merchant’s dashboard and is not returned by the API. It is written once: the reference never changes, and a mistake is corrected with a credit note (POST invoices/{invoice}/credit-notes). Only an issued, non-void document can carry one: a draft or a void invoice answers 409 invoice_state_conflict with error.reason not_issued, and an invoice that already has a reference answers 409 invoice_state_conflict with error.reason fiscal_reference_set, so a repeated call changes nothing. {invoice} is a p_id or UUID of this store; another store’s invoice reads exactly like one that does not exist (404). Answers the invoice as GET invoices/{invoice} reads it, with fiscal_reference set. Needs the Invoices app installed on the store (403 app_not_installed otherwise) and its own scope, merchant-invoices-fiscal-reference, which merchant-invoices-update does not carry. Fires invoices/update. Send an Idempotency-Key so a retried call replays the first answer.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Record the tax authority's reference for an invoice.
The reference is written once and never changes, so an app holds it under its own scope, apart from
merchant-invoices-update.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1044/fiscal-reference" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "reference": "TAX-2026-0044", "meta": { "qr_text": "https://einvoice.example.com/verify/TAX-2026-0044", "issued_at": "2026-09-24T10:20:00+01:00" } }'{ "status": "success", "message": "Tax authority reference recorded.", "data": { "id": 1044, "number": "INV-000044", "kind": "invoice", "status": "pending", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [], "installments": [], "credit_notes": [], "fiscal_reference": "TAX-2026-0044", "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T10:20:00+01:00" }}Requires scope merchant-invoices-record-payment.
Takes back a payment recorded by mistake: it stays on the invoice as history with voided_at and your reason as void_reason, stops counting toward amount_paid, and the invoice’s amount_due, status and instalments follow the payments that are left. Nothing moves through Queek: it settles the document only. {payment} is the p_id (or UUID) of a payment in the invoice’s payments, and {invoice} a p_id or UUID of this store; another store’s invoice, another invoice’s payment and an unknown id read like one that does not exist (404). A payment that is already void and a void invoice answer 409 invoice_state_conflict. The payments of an order-backed invoice (source order) are the order’s own and are not voidable here (404): refund them on the order. reason is required (3 to 255 characters). Answers the invoice as GET invoices/{invoice} reads it. Needs the Invoices app installed on the store (403 app_not_installed otherwise). It takes merchant-invoices-record-payment, the scope that records a payment (voiding the invoice itself is merchant-invoices-void). Fires invoices/update. A repeat answers 409 and changes nothing; send an Idempotency-Key so a retried call replays the first answer instead.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the invoice, as returned by the Merchant API.
Identifier of the invoice payment, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Void a payment recorded by mistake: the permission that records a payment is the one that takes it back (voiding
the invoice itself stays merchant-invoices-void). A reason is required and kept.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices/1042/payments/2001/void" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "reason": "Recorded against the wrong invoice." }'{ "status": "success", "message": "Payment voided.", "data": { "id": 1042, "number": "INV-000042", "kind": "invoice", "status": "pending", "credited": false, "source": "standalone", "order": null, "corrects_invoice": null, "customer": { "id": 90341 }, "title": "Wedding catering, 12 October", "currency": "USD", "buyer": { "name": "Alex Morgan", "email": "[email protected]", "phone": "+12025550148", "address": "88 Greenwich Street, New York, NY 10006", "tax_id": null }, "seller": { "name": "Northwind Goods", "address": "14 Mercer Street, New York, NY 10013", "registration_number": "REG 1849302", "tax_id": "12-3456789", "tax_id_label": "EIN" }, "lines": [ { "position": 1, "description": "Smokehouse Party Pack", "quantity": "10", "unit_price": "37.00", "tax_name": "Sales tax", "tax_rate": "8.00", "taxes": [ { "name": "Sales tax", "rate": "8.00", "amount": "26.64" } ], "line_total": "370.00", "discount_amount": "37.00", "tax_amount": "26.64" } ], "subtotal": "370.00", "discount": { "type": "percent", "value": "10.00", "total": "37.00" }, "tax_total": "26.64", "taxes_included": false, "tax_breakdown": [ { "name": "Sales tax", "rate": "8.00", "taxable": "333.00", "amount": "26.64" } ], "total_amount": "359.64", "amount_paid": "0.00", "amount_received": "0.00", "amount_refunded": "0.00", "amount_due": "359.64", "terms": "Balance due before the event.", "note": null, "language": "en", "payments": [ { "id": 2001, "source": "invoice", "kind": "payment", "amount": "180.00", "method": "bank_transfer", "is_cash": true, "reference": "WIRE-2210-8841", "paid_at": "2026-09-24T11:05:00+01:00", "voided_at": "2026-09-24T11:40:00+01:00", "void_reason": "Recorded against the wrong invoice." } ], "installments": [ { "sequence_no": 1, "expected_amount": "180.00", "paid_amount": "0.00", "status": "pending", "due_at": "2026-09-26", "paid_at": null }, { "sequence_no": 2, "expected_amount": "179.64", "paid_amount": "0.00", "status": "pending", "due_at": "2026-10-10", "paid_at": null } ], "credit_notes": [], "fiscal_reference": null, "issued_at": "2026-09-24T09:50:00+01:00", "due_at": "2026-10-10", "paid_at": null, "voided_at": null, "void_reason": null, "created_at": "2026-09-24T09:40:00+01:00", "updated_at": "2026-09-24T11:40:00+01:00" }}