Invoices API
The invoice module bills clients: invoices and their payments, refunds and credit notes, transactions, payment gateways, subscriptions, tax rules, quotes, saved payment methods, reports and the accounting sync. See Invoices for how billing works in the admin area. Clients reach their own invoices through the client calls; the guest calls serve the invoice and quote links.
Admin calls need Module access on the Invoice card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/invoice/get_list
Lists invoices, newest first, with filters. Each row is a full invoice, or a short row with summary.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
summary |
boolean | When true, each row has only the fields an invoice list needs (see Returns). Much faster for long lists. |
search |
string | Matches the invoice id, its number (also the printed number with series and padding, such as INV00040), a line title or the purchase order number. |
status |
mixed | unpaid, paid, refunded or canceled; an array of these for several; or not_sent for issued unpaid invoices that went out without their email. |
client_id |
integer | Only this client’s invoices. |
client |
string | A client’s first or last name (starting with), id or email. |
order_id |
integer | Only invoices with a line for this order. |
id |
integer | One invoice id. |
nr |
string | An invoice id or invoice number. |
approved |
boolean | When true, only issued (approved) invoices. False is ignored (drafts cannot be filtered on their own). |
currency |
string | A currency code, such as USD. |
created_at |
string | Issued on this day (any date PHP can read, such as 2026-11-17). |
date_from |
string | Issued at or after this date and time. |
date_to |
string | Issued on or before this day (the whole day). |
paid_at |
string | Paid on this day. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Without summary each row is the invoice object of get without the client_credit, payment_reversible, not_sent and reversible_payments fields. With summary each row has id, serie, nr, serie_nr, client_id, client ({id} or null), currency, tax, subtotal, total, status, due_at, paid_at, created_at, updated_at, buyer (first_name, last_name, email) and approved.
Example
Request parameters:
{ "status": "unpaid", "summary": true, "per_page": 1}result:
{ "pages": 12, "page": 1, "per_page": 1, "total": 12, "list": [ { "id": 42, "serie": "INV", "nr": "42", "serie_nr": "INV00042", "client_id": 7, "client": { "id": 7 }, "currency": "USD", "tax": 2, "subtotal": 10, "total": 12, "status": "unpaid", "due_at": "2026-11-24 10:00:00", "paid_at": null, "created_at": "2026-11-17 10:00:00", "updated_at": "2026-11-17 10:00:00", "buyer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "approved": true } ]}POST /api/admin/invoice/get
Returns one invoice with its lines, buyer, seller, client and payment state.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: The invoice: id, serie, nr, serie_nr (the printed number), client_id, hash (the secret key of the invoice’s public link), hash_expires_at, gateway_id, taxname, taxrate, currency, currency_rate, tax, subtotal, total, reverse_charge (true when the EU VAT reverse charge applies: no tax for a business buyer with a VAT number in another EU country), status (unpaid, paid, refunded or canceled), amount_paid, balance_due, credit_applied, pending_payment (a bank debit still clearing, or null), notes (the invoice notes; the client and guest calls return them too), po_number, text_1 and text_2 (texts above and below the lines), due_at, paid_at, created_at, updated_at, lines (each with id, title, period, quantity, unit, price, tax, taxed, charged, total, order_id, type, rel_id, task, status), buyer (first_name, last_name, company, company_vat, company_number, address, city, state, country, phone, phone_cc, email, zip), seller (company, company_vat, company_number, address, address_1 to address_3, phone, email, account_number, bank_name, bic), client (the client, or null), reminded_at, approved, income, refund, credit, subscribable, subscription (unit, cycle, period; only when subscribable) and orders (each id, title, expires_at, product_name, product_type). Staff calls also get client_credit (the client’s free account credit), payment_reversible (whether reverse_payment applies), not_sent (issued without its email) and reversible_payments (transaction ids reverse_part_payment can take back).
Errors:
- Invoice was not found (code 9999) when no invoice has this id.
Money is in the invoice’s currency. See Dates and money.
Example
Request parameters:
{ "id": 42}result:
{ "id": 42, "serie": "INV", "nr": "42", "client_id": 7, "serie_nr": "INV00042", "hash": "4f1c0e9b2a7d3c6e8f5a1b0c9d2e7f3a", "hash_expires_at": "2027-02-15 10:00:00", "gateway_id": 2, "taxname": "VAT", "taxrate": "20", "currency": "USD", "currency_rate": "1.000000", "tax": 2, "subtotal": 10, "total": 12, "reverse_charge": false, "status": "unpaid", "amount_paid": 0, "balance_due": 12, "credit_applied": 0, "pending_payment": null, "notes": null, "po_number": null, "text_1": null, "text_2": "Thank you for your business.", "due_at": "2026-11-24 10:00:00", "paid_at": null, "created_at": "2026-11-17 10:00:00", "updated_at": "2026-11-17 10:00:00", "lines": [ { "id": 81, "title": "Starter Hosting (example.com)", "period": "1M", "quantity": 1, "unit": "service", "price": 10, "tax": 0, "taxed": 1, "charged": 0, "total": 10, "order_id": "15", "type": "order", "rel_id": "15", "task": "renew", "status": "pending_payment" } ], "buyer": { "first_name": "Jane", "last_name": "Doe", "company": "", "company_vat": "", "company_number": "", "address": "1 Main Street", "city": "Springfield", "state": "", "country": "US", "phone": "+1 5550100", "phone_cc": "", "email": "jane@example.com", "zip": "12345" }, "seller": { "company": "Example Hosting", "company_vat": "", "company_number": "", "address": "10 Server Road", "address_1": "10 Server Road", "address_2": "", "address_3": "", "phone": "", "email": "billing@example.com", "account_number": null, "bank_name": null, "bic": null }, "client": { "id": 7, "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com" }, "reminded_at": null, "approved": true, "income": 0, "refund": 0, "credit": 0, "subscribable": false, "orders": [ { "id": 15, "title": "Starter Hosting", "expires_at": "2026-11-24 10:00:00", "product_name": "Starter Hosting", "product_type": "hosting" } ], "client_credit": 0, "payment_reversible": false, "not_sent": false, "reversible_payments": []}mark_as_paid
Section titled “mark_as_paid”POST /api/admin/invoice/mark_as_paid
Records a payment received outside the payment gateway (a bank transfer, cash) and marks the invoice paid, or records a part payment when amount is less than the balance due.
Permission: Manage invoices (invoice.manage_invoices); an Add funds invoice also needs Manage Client Balance (client.manage_balance)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
gateway_id |
integer | The payment method the money came through. Required when the invoice has none; it becomes the invoice’s. It must be enabled. |
transactionId |
string | The payment’s reference. Required for manual payment methods (Custom and methods built on it). |
amount |
number | The amount received, in the invoice’s currency, with at most 2 decimals. Leave it out to pay the whole balance due. Less than the balance due records a part payment and the invoice stays unpaid. |
Returns: true. An invoice that is already paid also returns true and nothing changes.
Errors:
- A draft invoice cannot be marked as paid. (code 9999): approve it first.
- Payment gateway is required when marking an invoice as paid. (code 9999)
- Payment gateway is not enabled (code 9999)
- Transaction ID is required when using the Custom payment gateway. (code 9999)
- Enter an amount greater than zero. (code 9999)
- The amount is more than the balance due (12.00). (code 9999)
- An Add funds invoice is paid in full only. (code 9999) for a part payment of an Add funds invoice.
- This transaction ID is already recorded. (code 9999)
- A paid or refunded invoice keeps its status, and only Refund marks an invoice refunded. (code 9999) for a refunded invoice.
Records a processed transaction, then (for a full payment) marks the invoice paid: the client gets the payment email, services on the invoice are activated or renewed, and an Add funds invoice credits the client’s balance. The payment gateway is never called.
Example
Request parameters:
{ "id": 42, "gateway_id": 1, "transactionId": "BANK-2026-1117"}result:
trueprepare
Section titled “prepare”POST /api/admin/invoice/prepare
Creates a draft invoice for a client, optionally with lines, and returns its id. The draft is filled with the client’s details, tax rule, next number and due date.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. A client without a currency gets the default currency. |
items |
array | Invoice lines. Each is an object with title (required), price (default 0; with prices that include tax, the price with tax on a taxed line), quantity (default 1), taxed (boolean), period (such as 1M), unit, and optionally type, rel_id, task, status. A line of type deposit is refused. |
gateway_id |
integer | The payment method of the invoice. |
text_1 |
string | Text shown above the lines. |
text_2 |
string | Text shown below the lines. Without it the default invoice note is used. |
approve |
boolean | Approve (issue) the invoice at once, as approve does. Without it the invoice is a draft, which cannot be marked as paid until it is approved. A failed approval is only logged. |
Returns: The new invoice id, as a string (such as "43").
Errors:
- Client not found (code 9999)
- Invoice item title is missing (code 9999)
- Deposit invoice items can only be created through the Add Funds flow. (code 9999)
Example
Request parameters:
{ "client_id": 7, "items": [ { "title": "Website migration", "price": 50, "quantity": 1, "taxed": true } ]}result:
"43"approve
Section titled “approve”POST /api/admin/invoice/approve
Issues a draft invoice: it becomes visible to the client and the invoice email is sent.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
use_credits |
boolean | Also pay the invoice from the client’s account credit when it covers the whole amount. |
send_email |
boolean | Send false (a JSON boolean) to issue it without the invoice email; the invoice then shows as not sent. Default: the email is sent. |
Returns: true.
Fires the approve events. The email is sent only when the total is above zero and the invoice is not paid. The invoice link’s lifetime starts again. An invoice with a payment method gets that method’s fee.
reverse_payment
Section titled “reverse_payment”POST /api/admin/invoice/reverse_payment
Undoes a payment staff recorded by mistake (a bank transfer that never arrived): the invoice is unpaid again, credit it used goes back, renewals move back and a service it set up is suspended.
Permission: Manage invoices (invoice.manage_invoices); an Add funds invoice also needs Manage Client Balance (client.manage_balance)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The paid invoice. |
Returns: true.
Errors:
- Only the payment of a paid invoice can be reversed. (code 9999)
- This invoice has a payment through a payment gateway or an imported payment. Refund it instead. (code 9999)
- This invoice was partly refunded, so its payment cannot be reversed. Refund the rest instead. (code 9999)
- This payment renewed a domain at its registrar, which cannot be undone here. Refund the invoice instead. (code 9999)
- The client has spent the credit this payment added, so it cannot be reversed. Refund this invoice by hand. (code 9999)
Works only when every payment on the invoice was recorded by staff; nothing is sent to a payment gateway. The staff transactions are marked reversed, never deleted. Affiliate commissions are reversed. The payment_reversible field of get says whether this call applies.
reverse_part_payment
Section titled “reverse_part_payment”POST /api/admin/invoice/reverse_part_payment
Takes back one part payment staff recorded on an unpaid invoice by mistake. The transaction is marked reversed and its amount comes off the client’s balance; the invoice stays unpaid.
Permission: Manage invoices (invoice.manage_invoices); an Add funds invoice also needs Manage Client Balance (client.manage_balance)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The unpaid invoice. |
transaction_id |
integer, required | The staff transaction to take back, one of reversible_payments from get. |
Returns: true.
Errors:
- Only a payment staff recorded on an unpaid invoice can be reversed here, and only once. (code 9999)
- The client has spent the credit this payment added, or other invoices have it set aside, so it cannot be reversed. (code 9999)
refund
Section titled “refund”POST /api/admin/invoice/refund
Refunds a paid invoice in full or in part, as the refund setting on the Invoices settings page says: a credit note or negative invoice is made, and the money goes back through the gateway, to account credit or is only recorded.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The paid invoice. |
amount |
number | The amount to refund, with tax. Leave it out (or send the total) for a full refund. A part refund needs refunds that are not handled by hand. |
refund_to |
string | gateway: send it back through the payment gateway that took the payment (PayPal with its REST API keys); credit: to the client’s account credit; manual or empty: record it only. |
to_credit |
boolean | Same as refund_to credit. |
note |
string | A note added to the credit note. |
reverse_commission |
boolean | A part refund also takes back the invoice’s affiliate commissions. A full refund always does. |
Returns: The id of the credit note (or negative invoice) made, or null when refunds are handled by hand and a full refund was asked (only events fire and affiliate commissions are reversed).
Errors:
- Only a paid invoice can be refunded, and only once. (code 9999)
- Refunds are handled by hand (Invoice settings), so this refund cannot be recorded. (code 9999) for a part refund, a refund to credit or through the gateway while Refunds Logic is manual.
- You can refund at most 12.00 USD. (code 9999)
- A refund to account credit cannot also be sent back through the payment gateway. (code 9999)
- This invoice has no payment that can be refunded through the payment gateway. (code 9999)
- A downgrade gave account credit for this service. Refund this invoice by hand. (code 9999)
The client gets the refund email. A refunded Add funds invoice takes its amount back from the client’s credit. This cannot be undone.
Example
Request parameters:
{ "id": 42, "amount": 6, "refund_to": "credit", "note": "Partial refund, service not used."}result:
44refund_gateway
Section titled “refund_gateway”POST /api/admin/invoice/refund_gateway
Tells whether the invoice has a payment that can be refunded through its payment gateway (PayPal with its REST API keys), and how much of it is left to refund.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: {gateway, left}: the gateway’s name and the most one payment has left to refund; null when no payment can be refunded through a gateway.
update
Section titled “update”POST /api/admin/invoice/update
Changes an invoice: its dates, number, status, tax, texts, buyer and seller details, payment method and lines. Only the fields you send change.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
status |
string | unpaid, paid or canceled. Setting paid records the payment as if marked paid (without a payment method’s transaction). A paid or refunded invoice keeps its status: use refund or reverse_payment. |
approved |
boolean | Whether the invoice is issued (visible to the client). Use approve or approve to issue it with its email. |
approve |
boolean | Approve the invoice after saving, as approve does. |
due_at |
string | Due date (YYYY-MM-DD); empty removes it. |
paid_at |
string | Payment date; empty removes it. A date alone on the same day keeps the stored time. |
created_at |
string | Issue date. A date alone on the same day keeps the stored time. |
serie |
string | Invoice series (prefix). |
nr |
string | Invoice number. |
taxrate |
string | Tax rate in percent. |
taxname |
string | Tax name, such as VAT. |
gateway_id |
integer | Payment method (must be enabled); null removes it. The new method’s fee is applied to an unpaid invoice. |
notes |
string | Notes on the invoice. The client and guest invoice calls return them too: keep secrets out. |
po_number |
string | Purchase order number, at most 64 characters; empty removes it. |
text_1 |
string | Text above the lines. |
text_2 |
string | Text below the lines. |
new_item |
object | A line to add: title, price, quantity, taxed, as in prepare. |
items |
object | Changes to existing lines, keyed by line id: each {title, price, quantity, taxed}. A line sent without taxed becomes untaxed. Lines of other invoices are ignored. |
seller_company |
string | Seller details on this invoice; also seller_company_vat, seller_company_number, seller_address, seller_phone, seller_email. |
buyer_first_name |
string | Buyer details on this invoice; also buyer_last_name, buyer_company, buyer_company_vat, buyer_company_number, buyer_address, buyer_city, buyer_state, buyer_country, buyer_zip, buyer_phone, buyer_email. |
Returns: true.
Errors:
- The lines and tax rate of a paid invoice cannot be changed. Refund it and make a new invoice. (code 9999)
- The issue and payment dates of a paid invoice cannot be changed. (code 9999)
- A paid invoice keeps its status. Undo a payment recorded by mistake with Reverse payment, or refund the invoice. (code 9999)
- Use Mark as Paid to record payment for an Add Funds invoice. (code 9999)
- Payment gateway not found (code 9999) or Payment gateway is not enabled (code 9999)
Cancelling an unpaid invoice releases its reserved promotion uses; reopening a cancelled one removes the credit that was applied to it. Fires the update events.
Example
Request parameters:
{ "id": 42, "due_at": "2026-12-01", "po_number": "PO-1185", "new_item": { "title": "Setup fee", "price": 15, "quantity": 1, "taxed": true }}result:
trueitem_delete
Section titled “item_delete”POST /api/admin/invoice/item_delete
Deletes one line of an unpaid invoice.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice line id (a lines[].id of get). |
Returns: true.
Errors:
- Invoice item was not found (code 9999)
- The lines and tax rate of a paid invoice cannot be changed. Refund it and make a new invoice. (code 9999)
Deleting a promotion’s discount line gives the reserved promotion use back and takes the promotion off the order.
get_failed_items
Section titled “get_failed_items”POST /api/admin/invoice/get_failed_items
Lists invoice lines whose task (activating or renewing a service after payment) failed for good.
Permission: View invoices (invoice.view)
No parameters.
Returns: A list of invoice lines, newest first, each with id, invoice_id, type, rel_id, task, status (failed), title, period, quantity, unit, price, charged, taxed, attempts, created_at and updated_at.
item_requeue
Section titled “item_requeue”POST /api/admin/invoice/item_requeue
Puts a failed invoice line back in the queue so its task runs again on the next cron run.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice line id. |
Returns: true.
Errors:
- Invoice item was not found (code 9999)
- Invoice item is not in a failed state (code 9999)
delete
Section titled “delete”POST /api/admin/invoice/delete
Deletes an unpaid or cancelled invoice.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: true.
Errors:
- A paid invoice cannot be deleted. Undo a payment recorded by mistake with Reverse payment, or refund the invoice. (code 9999)
- A paid or refunded invoice cannot be deleted. Refund it instead. (code 9999)
Reserved promotion uses are released. This cannot be undone.
renewal_invoice
Section titled “renewal_invoice”POST /api/admin/invoice/renewal_invoice
Makes and issues the renewal invoice of an order, and pays it from the client’s account credit when that covers it. When the order already has an unpaid invoice, that one is returned instead.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order id. |
due_days |
integer | Days until the new invoice is due. Default: the invoice due days setting. |
Returns: The invoice id.
Errors:
- Order not found (code 9999)
- This order was renewed a moment ago. Reload the page to see it. (code 9999) when a renewal of this order was paid in the last minute.
The invoice email is sent when the invoice is issued.
batch_pay_with_credits
Section titled “batch_pay_with_credits”POST /api/admin/invoice/batch_pay_with_credits
Pays every issued unpaid invoice whose client has enough account credit, as cron does.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer | Only this client’s invoices. |
Returns: true, also when nothing could be paid.
Skips Add funds invoices, invoices in another currency than the client’s credit, invoices with a bank debit clearing and invoices staff marked “Do not apply credit”. Paid invoices send the payment email and run their tasks.
pay_with_credits
Section titled “pay_with_credits”POST /api/admin/invoice/pay_with_credits
Pays one invoice from the client’s account credit when the free credit covers the whole amount.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: true. It is also true when the credit was not enough and the invoice stays unpaid: read the invoice again to know. Use apply_credit to pay part of it.
Errors:
- Client credit: You may not pay a deposit invoice with this payment gateway. (code 9999) for an Add funds invoice.
apply_credit
Section titled “apply_credit”POST /api/admin/invoice/apply_credit
Applies part or all of the client’s free account credit to an unpaid invoice. When it covers the balance due, the invoice is paid.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The unpaid invoice. |
amount |
number, required | The credit to apply, in the invoice’s currency. It can be at most the balance due and the client’s free credit (client_credit of get). |
Returns: true.
Errors:
- Enter an amount greater than zero. (code 9999)
- Credit can only be applied to an unpaid invoice. (code 9999)
- You can apply at most 12.00 USD. (code 9999)
- The credit is in USD and cannot pay an invoice in another currency. (code 9999)
- You may not pay a deposit invoice with this payment gateway. (code 9999) for an Add funds invoice.
Credit pays without the payment method’s fee; the fee is added again on what stays due.
promo_apply
Section titled “promo_apply”POST /api/admin/invoice/promo_apply
Applies an existing promotion to an order on an unpaid invoice, under the promotion’s rules (dates, uses, client groups, products and periods). A discount line is added.
Permission: Manage invoices (invoice.manage_invoices) and Manage promotions (product.manage_promos)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The unpaid invoice. |
promo_id |
integer, required | The promotion id. |
order_id |
integer | The order on the invoice to discount. Needed when the invoice has several orders. |
Returns: The discount taken off, before tax (a number).
Errors:
- Promo not found (code 9999)
- A promotion can only be applied to an unpaid invoice. (code 9999)
- Choose the order on this invoice. (code 9999)
- This order already has a discount on this invoice. (code 9999)
- This promotion code cannot be used for this client. (code 9999)
- This promotion does not apply to the product or billing period of this order. (code 9999)
The promotion use is reserved and counted when the invoice is paid; a recurring promotion also discounts the order’s renewals.
remove_credit
Section titled “remove_credit”POST /api/admin/invoice/remove_credit
Takes all account credit applied to an unpaid invoice back to the client’s free credit.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The unpaid invoice. |
Returns: true.
Errors:
- Credit can only be removed from an unpaid invoice. (code 9999)
batch_generate
Section titled “batch_generate”POST /api/admin/invoice/batch_generate
Makes and issues renewal invoices for every active order that is due soon, as cron does. Orders of one client, currency and expiry day share one invoice.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer | Only this client’s orders. |
Returns: true.
Each new invoice is paid from account credit when the credit covers it, and the invoice email is sent. An order that fails is logged and skipped.
batch_renewal_invoice
Section titled “batch_renewal_invoice”POST /api/admin/invoice/batch_renewal_invoice
Makes renewal invoices for several orders of one client at once. Orders that already have an unpaid invoice are skipped.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Order ids, all of one client. |
Returns: {invoice_ids, skipped_order_ids}: the new invoices and the orders skipped.
Errors:
- Order not found (code 9999)
- Selected orders must belong to one client (code 9999)
funds_invoice
Section titled “funds_invoice”POST /api/admin/invoice/funds_invoice
Makes and issues an Add funds invoice for a client. When it is paid, its amount goes to the client’s account credit.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. The client needs a currency. |
amount |
number, required | The amount, in the client’s currency. It must be positive and within the Add funds minimum and maximum. |
Returns: The new invoice id.
Errors:
- You need to enter a positive numeric value (code 9999)
- Adding funds to the account balance is currently disabled (code 980)
- Amount must be at least 10 (code 981)
- Amount cannot exceed 1000 (code 982)
- You must have at least one active order before you can add funds so you cannot proceed at the current time! (code 9999) when the client has no currency.
The invoice email is sent.
batch_activate_paid
Section titled “batch_activate_paid”POST /api/admin/invoice/batch_activate_paid
Runs the tasks of paid invoice lines that have not run yet (activating or renewing services), as cron does.
Permission: Manage invoices (invoice.manage_invoices)
No parameters.
Returns: true. A line that fails is logged and skipped.
batch_send_reminders
Section titled “batch_send_reminders”POST /api/admin/invoice/batch_send_reminders
Sends the payment reminders that are due, as cron does: before and after the due date, at the days set on the Invoices settings page.
Permission: Manage invoices (invoice.manage_invoices)
No parameters.
Returns: true.
Runs the due events (see batch_invoke_due_event) at most once in 24 hours; within that time a call fires them again for the built-in listeners, which decide which invoices get a reminder.
batch_invoke_due_event
Section titled “batch_invoke_due_event”POST /api/admin/invoice/batch_invoke_due_event
Fires the due events for every issued unpaid invoice: onEventBeforeInvoiceIsDue (with id and days_left) before the due date and onEventAfterInvoiceIsDue (with id and days_passed) on and after it. The built-in listeners send the reminders.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
once_per_day |
boolean | Default true: do nothing when the events ran in the last 24 hours. false runs them anyway. |
Returns: true when the events ran, false when they had already run in the last 24 hours.
send_reminder
Section titled “send_reminder”POST /api/admin/invoice/send_reminder
Sends the payment reminder email of one invoice now.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: true. A paid invoice gets no reminder and also returns true.
Sets reminded_at and fires the reminder events; the invoice link’s lifetime starts again.
send_invoice
Section titled “send_invoice”POST /api/admin/invoice/send_invoice
Sends the invoice email of an issued, unpaid invoice that went out without it (not_sent in get).
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: true.
Errors:
- Only an approved, unpaid invoice can be sent. (code 9999)
The invoice link’s lifetime starts again and the invoice no longer shows as not sent.
get_statuses
Section titled “get_statuses”POST /api/admin/invoice/get_statuses
Counts the invoices by status.
Permission: View invoices (invoice.view)
No parameters.
Returns: {total, paid, unpaid, refunded, canceled}: the number of invoices in each status.
Example
Request parameters:
{}result:
{ "total": 120, "paid": 98, "unpaid": 15, "refunded": 2, "canceled": 5}transaction_process_all
Section titled “transaction_process_all”POST /api/admin/invoice/transaction_process_all
Processes every received transaction (and any stuck in processing for too long), as cron does.
Permission: Manage transactions (invoice.manage_transactions)
No parameters.
Returns: true.
Errors:
- The first transaction that fails stops the run with its error; it is saved on that transaction (
statuserror).
transaction_process
Section titled “transaction_process”POST /api/admin/invoice/transaction_process
Processes one transaction now: its payment method checks it and the payment is applied to the invoice. Also retries a transaction in error.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The transaction id. |
Returns: true when it was processed.
Errors:
- Transaction not found (code 9999)
- This payment was reversed and is kept as a record only. Record a new payment instead. (code 9999)
- A processing failure returns its error and is saved on the transaction (
statuserror).
Fires onBeforeAdminTransactionProcess and onAfterAdminTransactionProcess.
transaction_update
Section titled “transaction_update”POST /api/admin/invoice/transaction_update
Changes the fields of a transaction record. Only the fields you send change.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The transaction id. |
invoice_id |
integer | The invoice it pays. |
txn_id |
string | The payment’s id at the gateway. |
txn_status |
string | The status at the gateway: see transaction_gateway_statuses. |
gateway_id |
integer | The payment method. |
amount |
number | The amount. |
currency |
string | The currency code. |
type |
string | See transaction_types. |
status |
string | See transaction_statuses. |
error |
string | Error text. |
error_code |
integer | Error code. |
validate_ipn |
boolean | Whether the gateway’s notice is checked when processed. |
note |
string | A note. |
Returns: true.
Only the record changes: no money moves and the invoice is not paid or unpaid. To apply a payment, use transaction_process. Fires the transaction update events.
transaction_create
Section titled “transaction_create”POST /api/admin/invoice/transaction_create
Records a payment as a transaction and processes it at once, as cron would.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
invoice_id |
integer | The invoice it pays. Required unless skip_validation is true. |
gateway_id |
integer | The payment method. Required unless skip_validation is true; an unknown id is always refused. |
amount |
number | The amount received (positive). |
currency |
string | The currency code of the amount. |
txn_id |
string | The payment’s id at the gateway. When a processed transaction of the same method has this id, that one’s id is returned and nothing new is recorded. |
note |
string | A note. |
skip_validation |
boolean | Record it without invoice_id and gateway_id. |
get |
object | The gateway notice’s query data, for a payment method that reads a notice. |
post |
object | The gateway notice’s form data. |
server |
object | The gateway notice’s request headers. |
http_raw_post_data |
string | The gateway notice’s raw body. |
source |
string | Where it came from. Default admin: then amount and currency are kept as sent. |
Returns: The transaction id.
Errors:
- Transaction invoice ID is missing (code 9999)
- Payment gateway ID is missing (code 9999)
- Invalid payment gateway (code 9999)
- Invoice was not found (code 9999)
A processing failure does not fail the call: it is saved on the transaction (status error, error); check it with transaction_get. Fires the transaction create events.
Example
Request parameters:
{ "invoice_id": 42, "gateway_id": 1, "amount": 12, "currency": "USD", "txn_id": "BANK-2026-1117", "note": "Bank transfer"}result:
31transaction_delete
Section titled “transaction_delete”POST /api/admin/invoice/transaction_delete
Deletes a transaction record.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The transaction id. |
Returns: true.
Errors:
- Transaction not found (code 9999)
Only the record goes: a payment it applied stays applied. To undo a payment staff recorded by mistake, use reverse_payment instead.
transaction_get
Section titled “transaction_get”POST /api/admin/invoice/transaction_get
Returns one transaction with the gateway notice it came from.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The transaction id. |
Returns: id, invoice_id, txn_id, txn_status, gateway_id, gateway (the method’s name), amount, currency, type, status, ip, validate_ipn, error, error_code, note, created_at, updated_at and ipn (the stored notice: source, get, post, http_raw_post_data, server).
Errors:
- Transaction not found (code 9999)
transaction_get_list
Section titled “transaction_get_list”POST /api/admin/invoice/transaction_get_list
Lists transactions, newest first, with filters.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
search |
string | Matches the note, invoice id, gateway transaction id or the stored notice. |
id |
integer | One transaction id. |
invoice_id |
integer | Only this invoice’s transactions. |
invoice_hash |
string | Only the transactions of the invoice with this hash. |
client_id |
integer | Only this client’s invoices’ transactions. |
gateway_id |
integer | Only this payment method. |
status |
string | See transaction_statuses. |
type |
string | See transaction_types. |
currency |
string | A currency code. |
txn_id |
string | The exact gateway transaction id. |
date_from |
string | Created at or after this date and time. |
date_to |
string | Created on or before this day (the whole day). |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a transaction as in transaction_get, without ipn.
Example
Request parameters:
{ "invoice_id": 42}result:
{ "pages": 1, "page": 1, "per_page": 100, "total": 1, "list": [ { "id": 31, "invoice_id": 42, "txn_id": "BANK-2026-1117", "txn_status": null, "gateway_id": 1, "gateway": "Bank transfer", "amount": 12, "currency": "USD", "type": null, "status": "processed", "ip": "203.0.113.5", "validate_ipn": null, "error": null, "error_code": null, "note": "Bank transfer transaction No: BANK-2026-1117", "created_at": "2026-11-17 11:00:00", "updated_at": "2026-11-17 11:00:00" } ]}transaction_client_totals
Section titled “transaction_client_totals”POST /api/admin/invoice/transaction_client_totals
Totals of a client’s processed transactions per currency: money in, money out (refunds) and the balance.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client id. |
Returns: A list, one row per currency: currency, in, out, balance.
Example
Request parameters:
{ "client_id": 7}result:
[ { "currency": "USD", "in": 240, "out": 12, "balance": 228 }]transaction_get_statuses
Section titled “transaction_get_statuses”POST /api/admin/invoice/transaction_get_statuses
Counts the transactions by status.
Permission: View invoices (invoice.view)
No parameters.
Returns: {total, received, approved, processing, processed, error}.
transaction_get_statuses_pairs
Section titled “transaction_get_statuses_pairs”POST /api/admin/invoice/transaction_get_statuses_pairs
The transaction statuses with their names, for a filter list.
Permission: View invoices (invoice.view)
No parameters.
Returns: An object of status => name: received Received, approved Approved, processing Processing, processed Processed, error Error, reversed Reversed.
transaction_statuses
Section titled “transaction_statuses”POST /api/admin/invoice/transaction_statuses
The transaction statuses with their longer names.
Permission: View invoices (invoice.view)
No parameters.
Returns: An object of status => name: received Received, approved Approved/Verified, processing Processing, processed Processed, error Error, reversed Reversed.
transaction_gateway_statuses
Section titled “transaction_gateway_statuses”POST /api/admin/invoice/transaction_gateway_statuses
The statuses a payment gateway can report for a transaction (txn_status).
Permission: View invoices (invoice.view)
No parameters.
Returns: An object of status => name: succeeded Succeeded, complete Complete, pending Pending validation, failed Failed, unknown Unknown.
transaction_types
Section titled “transaction_types”POST /api/admin/invoice/transaction_types
The transaction types.
Permission: View invoices (invoice.view)
No parameters.
Returns: An object of type => name: payment Payment, refund Refund, subscription_create Subscription create, subscription_cancel Subscription cancel, unknown Unknown.
transaction_claim_for_processing
Section titled “transaction_claim_for_processing”POST /api/admin/invoice/transaction_claim_for_processing
Marks a transaction as being processed, so no other worker processes it at the same time. For tools that process transactions themselves.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The transaction id. |
Returns: true when it was claimed (it was received, in error, or stuck in processing for too long); false when another worker has it or it is done.
Errors:
- Transaction ID is required (code 9999)
gateway_get_list
Section titled “gateway_get_list”POST /api/admin/invoice/gateway_get_list
Lists the installed payment gateways (payment methods) in the order clients see them.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
search |
string | Matches the name or the gateway code. |
enabled |
boolean | Only enabled (1) or disabled (0) ones. |
allow_single |
boolean | Filter on one-time payments allowed. |
allow_recurrent |
boolean | Filter on subscriptions allowed. |
test_mode |
boolean | Filter on test mode. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a gateway as in gateway_get.
gateway_get_pairs
Section titled “gateway_get_pairs”POST /api/admin/invoice/gateway_get_pairs
The installed payment gateways’ ids and names, for filters and lists.
No parameters.
Returns: An object of id => name, such as {"1": "Bank transfer", "2": "Stripe"}.
gateway_get_available
Section titled “gateway_get_available”POST /api/admin/invoice/gateway_get_available
Lists the payment gateway codes that can be installed (shipped with ClientFence or an active module, and not installed yet).
Permission: Manage payment gateways (invoice.manage_gateways)
No parameters.
Returns: A list of gateway codes, such as ["Mollie", "GoCardless"].
gateway_install
Section titled “gateway_install”POST /api/admin/invoice/gateway_install
Installs a payment gateway. It starts disabled, last in the order, with its own display name.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | A code from gateway_get_available. |
Returns: true.
Errors:
- Payment gateway is not available for installation. (code 9999)
Configure and enable it with gateway_update.
gateway_get
Section titled “gateway_get”POST /api/admin/invoice/gateway_get
Returns one payment gateway with its settings form. Secret settings (API keys) are never returned.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The gateway id. |
Returns: id, code, title, allow_single, allow_recurrent, accepted_currencies, supports_one_time_payments, supports_subscriptions, config (the settings; each secret one is null with a <name>_set flag saying whether it has a value), secret_fields, form (the settings form), description, enabled, test_mode, callback (the notice URL to give the gateway) and unpaid_invoices (how many unpaid invoices use it).
Errors:
- Gateway not found (code 9999)
gateway_copy
Section titled “gateway_copy”POST /api/admin/invoice/gateway_copy
Makes a disabled copy of a payment gateway with the same settings, named “
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The gateway to copy. |
Returns: The new gateway id.
Errors:
- Gateway not found (code 9999)
gateway_update
Section titled “gateway_update”POST /api/admin/invoice/gateway_update
Changes a payment gateway’s name, settings, currencies and switches. An enabled gateway’s settings are checked (and its API keys tested, where the gateway can) before saving.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The gateway id. |
title |
string | The name clients see. |
config |
object | Settings to change, by name (see form in gateway_get). A secret setting sent empty keeps its value. fee sets the gateway fee. |
accepted_currencies |
array | Currency codes this gateway takes. |
enabled |
boolean | Turn the gateway on or off. |
allow_single |
boolean | Allow one-time payments. |
allow_recurrent |
boolean | Allow subscriptions. |
test_mode |
boolean | Use the gateway’s test (sandbox) mode. |
replacement_id |
integer | When turning off a gateway that unpaid invoices use: the enabled gateway they move to (with its fee). |
Returns: true.
Errors:
- Gateway not found (code 9999)
- Payment gateway configuration error: … (code 819) when the settings are not complete for the chosen mode
- Choose an enabled gateway for the unpaid invoices of this gateway. (code 9999)
Example
Request parameters:
{ "id": 2, "enabled": true, "test_mode": false, "accepted_currencies": [ "USD", "EUR" ]}result:
truegateway_move
Section titled “gateway_move”POST /api/admin/invoice/gateway_move
Moves a payment gateway one place up or down in the order clients see the payment methods.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The gateway id. |
direction |
string | up; anything else moves it down. |
Returns: true, or false when it is already first (up) or last (down).
Errors:
- Gateway not found (code 9999)
gateway_delete
Section titled “gateway_delete”POST /api/admin/invoice/gateway_delete
Deletes a payment gateway. Its unpaid invoices move to a replacement; paid invoices and transactions keep their history.
Permission: Manage payment gateways (invoice.manage_gateways)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The gateway id. |
replacement_id |
integer | An enabled gateway for its unpaid invoices. Required when it has any. |
Returns: true.
Errors:
- This gateway has active subscriptions. Disable it instead of deleting it. (code 9999)
- Clients have saved payment methods on this gateway. Disable it instead of deleting it. (code 9999)
- Choose an enabled gateway for the unpaid invoices of this gateway. (code 9999)
The gateway’s stored customer ids and cached products are removed too. This cannot be undone.
subscription_get_list
Section titled “subscription_get_list”POST /api/admin/invoice/subscription_get_list
Lists payment gateway subscriptions, newest first, with filters.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
search |
string | A subscription id or gateway subscription id (sid). |
id |
integer | One subscription id. |
sid |
string | The gateway’s subscription id. |
client_id |
integer | Only this client’s subscriptions. |
status |
string | Such as active or canceled. |
currency |
string | A currency code. |
date_from |
string | Created on or after this date (YYYY-MM-DD) or Unix time. |
date_to |
string | Created on or before this date (YYYY-MM-DD, to the end of the day) or Unix time. |
invoice_id |
integer | Not usable in this version: the filter ends in an error. |
gateway_id |
integer | Not usable in this version: the filter ends in an error. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a subscription as in subscription_get.
subscription_create
Section titled “subscription_create”POST /api/admin/invoice/subscription_create
Records a subscription a client has at a payment gateway.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
gateway_id |
integer, required | The payment gateway. |
currency |
string, required | Must be the client’s currency. |
sid |
string | The subscription id at the gateway. |
status |
string | active or canceled. |
period |
string | The billing period code, such as 1M (every month) or 1Y. |
amount |
number | The amount billed each period. |
rel_type |
string | Type of the related item. |
rel_id |
integer | Id of the related item. |
Returns: The new subscription id.
Errors:
- Client not found (code 9999)
- Payment gateway not found (code 9999)
- Client currency must match subscription currency. Check if clients currency is defined. (code 9999)
Nothing is created at the gateway: this only records it.
subscription_update
Section titled “subscription_update”POST /api/admin/invoice/subscription_update
Changes a subscription record. Setting status to canceled also cancels it at the payment gateway.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The subscription id. |
status |
string | active or canceled. |
sid |
string | The subscription id at the gateway. |
period |
string | The billing period code. |
amount |
number | The amount billed each period. |
currency |
string | The currency code. |
Returns: true.
Errors:
- Subscription not found (code 9999)
- Cancel subscription I-ABC123 in PayPal: ClientFence marks it canceled when PayPal reports it. (code 9999) for a gateway that cannot cancel by API.
subscription_get
Section titled “subscription_get”POST /api/admin/invoice/subscription_get
Returns one subscription, by id or by the gateway’s subscription id.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
id |
integer | The subscription id. Send id or sid. |
sid |
string | The subscription id at the gateway. |
Returns: id, sid, period, amount, currency, status, created_at, updated_at, client (the client) and gateway (the gateway as in gateway_get).
Errors:
- Subscription ID was not passed (code 9999) when neither
idnorsidis sent - Subscription not found (code 9999)
subscription_delete
Section titled “subscription_delete”POST /api/admin/invoice/subscription_delete
Deletes a subscription record. Nothing is cancelled at the gateway.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The subscription id. |
Returns: true.
Errors:
- Subscription not found (code 9999)
tax_delete
Section titled “tax_delete”POST /api/admin/invoice/tax_delete
Deletes a tax rule.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The tax rule id. |
Returns: true.
Errors:
- Tax rule not found (code 9999)
Invoices already made keep their tax.
tax_create
Section titled “tax_create”POST /api/admin/invoice/tax_create
Creates a tax rule: a rate for a country and state, a whole country, or everyone.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
name |
string, required | The tax name on invoices, such as VAT. |
taxrate |
string, required | The rate in percent, 0 to 100 (a decimal comma is read as a point). |
country |
string | Two-letter country code; empty for all countries. |
state |
string | State or region; empty for the whole country. |
Returns: The new tax rule id.
Errors:
- The tax rate must be a number from 0 to 100. (code 9999)
A client is taxed by the rule of their country and state, else of their whole country, else the rule for all countries.
Example
Request parameters:
{ "name": "VAT", "taxrate": "20", "country": "GB"}result:
3tax_get
Section titled “tax_get”POST /api/admin/invoice/tax_get
Returns one tax rule.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The tax rule id. |
Returns: id, level, name, country, state, taxrate, created_at, updated_at.
Errors:
- Tax rule not found (code 9999)
tax_update
Section titled “tax_update”POST /api/admin/invoice/tax_update
Changes a tax rule. Send all its fields: a missing country or state becomes empty.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The tax rule id. |
name |
string, required | The tax name. |
taxrate |
string, required | The rate in percent, 0 to 100. |
country |
string | Two-letter country code; empty for all countries. |
state |
string | State or region; empty for the whole country. |
Returns: true.
Errors:
- Tax rule not found (code 9999)
- The tax rate must be a number from 0 to 100. (code 9999)
tax_get_list
Section titled “tax_get_list”POST /api/admin/invoice/tax_get_list
Lists the tax rules, newest first.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a tax rule as in tax_get.
tax_setup_eu
Section titled “tax_setup_eu”POST /api/admin/invoice/tax_setup_eu
Meant to set up the EU VAT rules for every member state. In ClientFence 1.0.57 the call fails with a server error and changes nothing: add the rules with tax_create.
Permission: Manage tax rules (invoice.manage_tax)
No parameters.
Returns: Nothing: the call ends in an error.
batch_delete
Section titled “batch_delete”POST /api/admin/invoice/batch_delete
Deletes several invoices. Each goes through delete with its own checks; one that cannot be deleted is skipped with the reason.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Invoice ids. |
Returns: {done, skipped}: the ids deleted, and an object of skipped id => reason.
Example
Request parameters:
{ "ids": [ 40, 41 ]}result:
{ "done": [ 40 ], "skipped": { "41": "A paid invoice cannot be deleted. Undo a payment recorded by mistake with Reverse payment, or refund the invoice." }}batch_mark_paid
Section titled “batch_mark_paid”POST /api/admin/invoice/batch_mark_paid
Marks several invoices paid, as mark_as_paid with each invoice’s own payment method. A manual method’s payment is recorded without a transaction id.
Permission: Manage invoices (invoice.manage_invoices); Add funds invoices also need Manage Client Balance (client.manage_balance)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Invoice ids. |
Returns: {done, skipped}: the ids done, and an object of skipped id => reason (such as an invoice without a payment method).
batch_cancel
Section titled “batch_cancel”POST /api/admin/invoice/batch_cancel
Cancels several unpaid invoices.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Invoice ids. |
Returns: {done, skipped}: the ids cancelled, and an object of skipped id => reason (paid and other non-unpaid invoices are skipped).
batch_mark_unpaid
Section titled “batch_mark_unpaid”POST /api/admin/invoice/batch_mark_unpaid
Makes several cancelled invoices unpaid again.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Invoice ids. |
Returns: {done, skipped}: the ids changed, and an object of skipped id => reason (only cancelled invoices change).
batch_send_reminder
Section titled “batch_send_reminder”POST /api/admin/invoice/batch_send_reminder
Sends the payment reminder of several issued unpaid invoices.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Invoice ids. |
Returns: {done, skipped}: the ids reminded, and an object of skipped id => reason (drafts and invoices that are not unpaid are skipped).
batch_delete_subscription
Section titled “batch_delete_subscription”POST /api/admin/invoice/batch_delete_subscription
Deletes several subscription records, as subscription_delete.
Permission: Manage subscriptions (invoice.manage_subscriptions)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Subscription ids. |
Returns: true.
Errors:
- Subscription not found (code 9999): the call stops there; the ones before it are already deleted.
batch_delete_transaction
Section titled “batch_delete_transaction”POST /api/admin/invoice/batch_delete_transaction
Deletes several transaction records, as transaction_delete.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Transaction ids. |
Returns: true.
Errors:
- Transaction not found (code 9999): the call stops there; the ones before it are already deleted.
batch_delete_tax
Section titled “batch_delete_tax”POST /api/admin/invoice/batch_delete_tax
Deletes several tax rules.
Permission: Manage tax rules (invoice.manage_tax)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | Tax rule ids. |
Returns: true.
Errors:
- Tax rule not found (code 9999): the call stops there; the ones before it are already deleted.
report_catalog
Section titled “report_catalog”POST /api/admin/invoice/report_catalog
Lists the reports of the Reports page, by group, that this staff member may run.
Permission: View invoices (invoice.view); the Clients group needs View Client Details (client.view) and the Support group View support tickets (support.view), or it is left out
No parameters.
Returns: An object of group => {title, reports}, where reports is an object of report key => {title, description}. Groups: billing (statement, aging_invoices, monthly_transactions, income_forecast, sales_tax, top_clients, credits), clients (clients_by_country, suspensions) and support (ticket_replies).
Example
Request parameters:
{}result:
{ "billing": { "title": "Billing", "reports": { "aging_invoices": { "title": "Aging Invoices", "description": "Unpaid invoices by how long they are overdue." } } }}report
Section titled “report”POST /api/admin/invoice/report
Runs a report and returns its table. Money is in one currency at a time.
Permission: View invoices (invoice.view), and for a report of the Clients or Support group also that module’s view permission (see report_catalog)
| Parameter | Type | Description |
|---|---|---|
report |
string, required | The report key, from report_catalog. |
month |
string | The month (YYYY-MM) of a monthly report. Default: this month. |
from |
string | Start date (YYYY-MM-DD) for reports with a period. |
to |
string | End date (YYYY-MM-DD). |
currency |
string | Currency code. Default: the default currency. |
client_id |
integer | A client id, for the reports that take one (statement, credits). |
min |
number | Smallest amount, for reports that filter by amount. |
max |
number | Largest amount. |
Returns: The report: key, group, title, description, fields (the filters it takes: name, type, label), filters (the values used), currency, currencies, columns (each with a label and a type: text, int, money, date, month, country or link), rows, total (a totals row or null), truncated (true when only the first 5,000 rows are shown), notice, client and pdf.
Errors:
- Report not found (code 404)
- Choose one of the currencies. (code 9999)
- Enter a client ID. (code 9999)
Example
Request parameters:
{ "report": "monthly_transactions", "month": "2026-10", "currency": "USD"}report_csv
Section titled “report_csv”POST /api/admin/invoice/report_csv
Runs a report (as report) and returns it as a CSV file download.
Permission: Export invoice data (invoice.export), plus what report needs
| Parameter | Type | Description |
|---|---|---|
report |
string, required | The report key. |
month |
string | Filters as in report: also from, to, currency, client_id, min, max. |
Returns: A CSV file (UTF-8 with a byte order mark, so Excel reads every language): the column titles, the rows and the total, plain numbers with two decimals for money, ISO dates. Not JSON.
quote_get_list
Section titled “quote_get_list”POST /api/admin/invoice/quote_get_list
Lists quotes, newest first.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
stage |
string | draft, delivered, on_hold, accepted, lost or dead. |
client_id |
integer | Only this client’s quotes. |
search |
string | A quote number (with or without #), subject, name, company or email. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 100. Default 30. |
Returns: {list, total, page, per_page, pages}; each row is a quote as in quote_get.
quote_get
Section titled “quote_get”POST /api/admin/invoice/quote_get
Returns one quote with its lines, totals and recipient.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The quote id. |
Returns: id, hash (the key of its link), client_id (null for a prospect), recipient (first_name, last_name, name, company, email, country, prospect, deleted), currency, subject, stage, stage_title, open (can still be sent or accepted), expired, valid_until, proposal, customer_notes, admin_notes, taxname, taxrate, invoice_id (once accepted), sent_at, accepted_at, declined_at, created_at, updated_at, items (each description, quantity, price, discount (percent), taxed, unit_price (after the discount), amount, tax), subtotal, tax and total.
Errors:
- Quote not found (code 404)
Example
Request parameters:
{ "id": 5}result:
{ "id": 5, "hash": "9c1e5b7a2f4d6e8a0b3c5d7e9f1a2b4c6d8e0f1a", "client_id": 7, "recipient": { "first_name": "Jane", "last_name": "Doe", "name": "Jane Doe", "company": "", "email": "jane@example.com", "country": "US", "prospect": false, "deleted": false }, "currency": "USD", "subject": "Website migration", "stage": "delivered", "stage_title": "Delivered", "open": true, "expired": false, "valid_until": "2026-12-01", "proposal": "Moving two sites to Example Hosting.", "customer_notes": "", "admin_notes": "", "taxname": "", "taxrate": 0, "invoice_id": null, "sent_at": "2026-11-17 12:00:00", "accepted_at": null, "declined_at": null, "created_at": "2026-11-17 11:50:00", "updated_at": "2026-11-17 12:00:00", "items": [ { "description": "Site migration", "quantity": 2, "price": 50, "discount": 10, "taxed": false, "unit_price": 45, "amount": 90, "tax": 0 } ], "subtotal": 90, "tax": 0, "total": 90}quote_save
Section titled “quote_save”POST /api/admin/invoice/quote_save
Creates a quote, or changes one when id is sent. A quote is for a client or for a prospect (name and email, no account yet). The tax follows the client’s tax rule (for a prospect, the rule of its country).
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer | The quote to change. An accepted quote only takes admin_notes. |
subject |
string, required | At most 255 characters. |
items |
array, required | 1 to 100 lines, each {description, quantity, price, discount, taxed}: description up to 255 characters, whole quantity from 1, price with at most 2 decimals, discount a percentage 0 to 100. Lines with no description and no price are left out. |
client_id |
integer | The client. Without it, the prospect fields below are used. |
first_name |
string | Prospect’s first name (required for a prospect); also last_name and company, each up to 100 characters. |
email |
string | Prospect’s email (required for a prospect). An email that belongs to a client is refused: quote that client. |
country |
string | Prospect’s two-letter country code. |
currency |
string | Prospect’s currency; default the default currency. A client’s quote uses the client’s currency. |
stage |
string | draft (default), delivered, on_hold, lost or dead. A quote becomes accepted only by being accepted. |
valid_until |
string | Last day it can be accepted (YYYY-MM-DD). |
proposal |
string | Text shown with the quote, up to 20,000 characters. |
customer_notes |
string | Notes the client sees, up to 20,000 characters. |
admin_notes |
string | Staff notes, up to 20,000 characters. |
Returns: The quote id.
Errors:
- Quote not found (code 404)
- Enter the subject of the quote. (code 9999)
- Add at least one line to the quote. (code 9999)
- Choose a client, or enter the first name and email of the prospect. (code 9999)
- Client #7 has this email: choose that client instead. (code 9999)
Changing the recipient gives the quote a new link, so the old one stops working.
Example
Request parameters:
{ "client_id": 7, "subject": "Website migration", "valid_until": "2026-12-01", "items": [ { "description": "Site migration", "quantity": 2, "price": 50, "discount": 10 } ]}result:
5quote_delete
Section titled “quote_delete”POST /api/admin/invoice/quote_delete
Deletes a quote. An invoice made from it stays.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The quote id. |
Returns: true.
Errors:
- Quote not found (code 404)
quote_send
Section titled “quote_send”POST /api/admin/invoice/quote_send
Emails the quote with its PDF and link to the client or prospect. A draft becomes delivered.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The quote id. |
Returns: true.
Errors:
- Quote not found (code 404)
- Only a quote that is not accepted, lost or dead can be sent. (code 9999)
- Add at least one line to the quote. (code 9999)
- A mail error is returned as an error.
A client also gets a notice in the client area bell.
quote_accept
Section titled “quote_accept”POST /api/admin/invoice/quote_accept
Accepts a quote for the client (accepted by phone or email): a prospect gets a client account, and an unpaid invoice with the quote’s lines is made, issued and emailed. Staff may accept an expired quote.
Permission: Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The quote id. |
Returns: The new invoice id.
Errors:
- Quote not found (code 404)
- This quote is already accepted. (code 9999)
- This quote can no longer be accepted. (code 9999) for a lost or dead quote
- This quote is in EUR, but the account uses USD. Please contact us. (code 9999)
A new account gets the welcome email with a link to set its password.
quote_pdf
Section titled “quote_pdf”POST /api/admin/invoice/quote_pdf
Returns a quote as a PDF, in the recipient’s language.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The quote id. |
Returns: A PDF file, not JSON.
Errors:
- Quote not found (code 404)
statement_pdf
Section titled “statement_pdf”POST /api/admin/invoice/statement_pdf
Returns a client’s account statement (invoices, payments and account credit with the running balance) as a PDF in the staff member’s language.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
from |
string | Start date (YYYY-MM-DD); earlier lines make the opening balance. |
to |
string | End date (YYYY-MM-DD). |
Returns: A PDF file, not JSON.
Errors:
- Client not found (code 9999)
- Enter the dates as year-month-day. (code 9999)
- The start date is after the end date. (code 9999)
export_csv
Section titled “export_csv”POST /api/admin/invoice/export_csv
Exports all invoices as a CSV file.
Permission: View invoices (invoice.view) and Export invoice data (invoice.export)
| Parameter | Type | Description |
|---|---|---|
headers |
array | The columns to export, from: id, client_id, serie, nr, currency, currency_rate, credit, base_income, base_refund, refund, notes, text_1, text_2, status, the seller_* and buyer_* fields, gateway_id, approved, taxname, taxrate, due_at, reminded_at, paid_at, created_at, updated_at, po_number. Unknown names are dropped. Default: a standard set of these. |
Returns: A CSV file named invoices.csv, not JSON.
receipts_update
Section titled “receipts_update”POST /api/admin/invoice/receipts_update
Sets the help desk in which payment receipts that clients upload open a ticket (on the Invoices settings page).
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
receipt_helpdesk |
integer | The help desk id. Empty: the first help desk. |
Returns: true.
Errors:
- The help desk for payment receipts was not found. (code 9999)
card_settings_update
Section titled “card_settings_update”POST /api/admin/invoice/card_settings_update
Sets when saved cards and other saved payment methods are charged for unpaid invoices.
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
card_days_before |
integer | Days before the due date of the first charge, 0 to 30. Default 0. |
card_retry_every |
integer | Days between tries after a failed charge, 1 to 30. Default 7. |
card_retry_count |
integer | Retries after the first failure, 0 to 5. Default 2. |
Returns: true.
Errors:
- Days before the due date must be a whole number from 0 to 30. (code 9999)
- Days between retries must be a whole number from 1 to 30. (code 9999)
- Retries must be a whole number from 0 to 5. (code 9999)
A setting you leave out is saved with its default value.
card_find
Section titled “card_find”POST /api/admin/invoice/card_find
Looks at Stripe for saved cards of clients who have none in ClientFence (after a move from another billing system), 25 clients per call.
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
after_id |
integer | Start after this client id: the next value of the previous call. Default 0. |
Returns: {checked, found, next}: clients checked, cards found, and the after_id for the next call (null when done).
Errors:
- Saved cards are not available. (code 9999) without an enabled Stripe gateway.
card_get
Section titled “card_get”POST /api/admin/invoice/card_get
The saved payment method an invoice’s client is charged to.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The invoice id. |
Returns: A label such as "Visa •••• 4242 (12/2028)" or "PayPal jane@example.com", or null when the client has none.
Errors:
- Invoice not found (code 9999)
card_list
Section titled “card_list”POST /api/admin/invoice/card_list
A client’s saved cards and PayPal accounts, one per payment gateway, and which one is charged.
Permission: View invoices (invoice.view)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
Returns: A list of {card, pays}: the method’s label, and whether it is the one charged.
Example
Request parameters:
{ "client_id": 7}result:
[ { "card": "Visa •••• 4242 (12/2028)", "pays": true }]paypal_balances
Section titled “paypal_balances”POST /api/admin/invoice/paypal_balances
The balance of each enabled PayPal gateway (PayPal Email with its REST API keys, PayPal Auto-Pay) whose dashboard balance is turned on.
Permission: View invoices (invoice.view)
No parameters.
Returns: A list of {gateway, test_mode, balances, error}: balances is a list of {currency, amount}; error is a message when PayPal did not answer, else null.
PayPal is asked at most every 10 minutes; calls in between get the stored answer.
card_charge
Section titled “card_charge”POST /api/admin/invoice/card_charge
Charges the client’s saved card or other saved payment method for an unpaid invoice now.
Permission: Manage transactions (invoice.manage_transactions)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The unpaid invoice. |
Returns: true when the charge went through.
Errors:
- Invoice not found (code 9999)
- The client has no saved payment method. (code 9999)
- A declined or failed charge returns the gateway’s reason as the error message.
A staff charge does not count as one of the automatic tries and sends the client no failure email.
accounting_get
Section titled “accounting_get”POST /api/admin/invoice/accounting_get
The accounting sync settings (Xero, FreeAgent or QuickBooks), the connection, the mapping lists and the last 50 sync records.
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: program, programs (key => name), client_id (the app’s client id), has_secret, connected, lists (accounts, tax_rates, error from the program), organisation, redirect_uri (to enter in the program’s app), start_date, backfill_from, paid_only, has_sandbox, sandbox, paused (why sending waits, or empty), sales_account, bank_accounts, tax_map, taxes, gateways (id, name), counts (records per status) and rows (each id, entity, local_id, remote_id, status, attempts, last_error, synced_at, updated_at, number), plus notice. The client secret and tokens are never returned.
accounting_save
Section titled “accounting_save”POST /api/admin/invoice/accounting_save
Saves the accounting sync settings. Only the settings you send change. Choosing another program, app or environment disconnects it.
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
program |
string | xero, freeagent or quickbooks; empty turns the sync off. |
client_id |
string | The app’s client id at the program. |
client_secret |
string | The app’s client secret; saved only when not empty. |
start_date |
string | Invoices issued from this date (YYYY-MM-DD) are sent. Default: today when a program is chosen. |
sandbox |
boolean | Use the program’s test environment, where it has one. |
paid_only |
boolean | Send an invoice only once it is paid. |
sales_account |
string | The program’s sales account. |
bank_accounts |
object | Payment gateway id (or credit for account credit) => the program’s bank account. |
tax_map |
object | Tax key (from taxes of accounting_get) => the program’s tax rate. |
Returns: true.
Errors:
- Choose an accounting program from the list. (code 9999)
- The account and tax choices could not be read. Reload the page and try again. (code 9999)
accounting_connect
Section titled “accounting_connect”POST /api/admin/invoice/accounting_connect
Starts connecting the accounting program: returns the program’s sign-in address to send the staff member to.
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: The sign-in URL. The program sends the staff member back to the redirect_uri, which must happen in the same staff session within 10 minutes.
accounting_disconnect
Section titled “accounting_disconnect”POST /api/admin/invoice/accounting_disconnect
Disconnects the accounting program (forgets its tokens). The sync records stay.
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: true.
accounting_lists
Section titled “accounting_lists”POST /api/admin/invoice/accounting_lists
The connected program’s accounts and tax rates, for the mapping lists.
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: {accounts, tax_rates} as the program lists them.
Errors:
- The program’s error message when it refuses the call.
accounting_run
Section titled “accounting_run”POST /api/admin/invoice/accounting_run
Sends now (“Send now”): one run of the accounting sync, as cron does.
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: {sent, failed, waiting}: how many records were sent and failed, and whether more are waiting for the next run. When another run is busy: {sent: 0, failed: 0, waiting: false, busy: true}.
accounting_resend
Section titled “accounting_resend”POST /api/admin/invoice/accounting_resend
Sends one sync record again on the next run (“Send again”): its attempts start over.
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The sync record id (a rows[].id of accounting_get). |
Returns: true.
Errors:
- Sync record not found. (code 9999)
accounting_resend_all
Section titled “accounting_resend_all”POST /api/admin/invoice/accounting_resend_all
Sends every failed or stopped sync record of the current program again on the next runs (“Send all again”).
Permission: Manage settings (invoice.manage_settings)
No parameters.
Returns: How many records were queued again.
accounting_backfill
Section titled “accounting_backfill”POST /api/admin/invoice/accounting_backfill
Also sends invoices issued from an earlier date than the start date (“Send older invoices”).
Permission: Manage settings (invoice.manage_settings)
| Parameter | Type | Description |
|---|---|---|
from |
string, required | The date (YYYY-MM-DD), before the start date. |
Returns: true.
Errors:
- Choose a date before the start date. (code 9999)
Client calls
Section titled “Client calls”get_list (client)
Section titled “get_list (client)”POST /api/client/invoice/get_list
Lists the signed-in client’s issued invoices, newest first. Drafts are never listed.
| Parameter | Type | Description |
|---|---|---|
status |
mixed | unpaid, paid, refunded or canceled, or an array of these. |
search |
string | Matches the invoice number, a line title or the purchase order number. |
order_id |
integer | Only invoices with a line for this order. |
currency |
string | A currency code. |
date_from |
string | Issued at or after this date and time. |
date_to |
string | Issued on or before this day (the whole day). |
paid_at |
string | Paid on this day. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is the invoice object of the admin get call, without its staff-only fields (client_credit, payment_reversible, not_sent, reversible_payments).
Authorized users of the account need the View and pay invoices permission.
get (client)
Section titled “get (client)”POST /api/client/invoice/get
Returns one of the signed-in client’s invoices by its hash.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash (hash in the invoice list). |
Returns: The invoice object, as in get_list.
Errors:
- Invoice was not found (code 9999) when the hash is not one of this client’s invoices.
Authorized users need the View and pay invoices permission.
apply_credit (client)
Section titled “apply_credit (client)”POST /api/client/invoice/apply_credit
Applies part or all of the client’s account credit to one of their unpaid invoices. When it covers the balance due, the invoice is paid.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash. |
amount |
number, required | The credit to apply, at most the balance due and the free credit. |
Returns: true.
Errors:
- Invoice was not found (code 9999)
- Credit can only be applied to an unpaid invoice. (code 9999)
- You can apply at most 12.00 USD. (code 9999)
- Enter an amount greater than zero. (code 9999)
Authorized users need the View and pay invoices permission.
mass_pay (client)
Section titled “mass_pay (client)”POST /api/client/invoice/mass_pay
Makes one grouped invoice that pays several unpaid invoices together (Mass Pay). Pay it like any invoice; once paid, each invoice it lists is paid.
| Parameter | Type | Description |
|---|---|---|
ids |
array | The invoice ids to pay together (at least two). |
all |
boolean | Group every unpaid issued invoice that can be paid together; the others are left out. |
Returns: The grouped invoice’s hash.
Errors:
- Choose at least two unpaid invoices to pay together. (code 9999)
- Invoice INV00042 cannot be paid together with other invoices. (code 9999) for an invoice that is not unpaid, is in another currency, is an Add funds invoice or has a payment clearing.
- Invoice was not found (code 9999)
Each line is what the invoice owes at that moment, without its own payment method fee; the grouped invoice carries the fee of the method that pays it. Authorized users need the View and pay invoices permission.
renewal_invoice (client)
Section titled “renewal_invoice (client)”POST /api/client/invoice/renewal_invoice
Renews a service now (Renew Now): makes and issues its renewal invoice, paid from account credit when that covers it. When the service already has an unpaid invoice, that one is returned.
| Parameter | Type | Description |
|---|---|---|
order_id |
integer, required | The client’s order (service) id. |
Returns: The invoice hash.
Errors:
- Order not found (code 9999)
- Only an active or suspended service can be renewed. (code 9999)
- This service is set to be cancelled at the end of its period, so it cannot be renewed. (code 9999)
- This order was renewed a moment ago. Reload the page to see it. (code 9999)
- The invoice for this service is being prepared. You will receive it by email. (code 9999) when staff hold a draft invoice for it
Authorized users need the View and pay invoices permission.
funds_invoice (client)
Section titled “funds_invoice (client)”POST /api/client/invoice/funds_invoice
Makes and issues an Add funds invoice. When it is paid, its amount goes to the client’s account credit.
| Parameter | Type | Description |
|---|---|---|
amount |
number, required | The amount, in the client’s currency, positive and within the Add funds minimum and maximum. |
Returns: The invoice hash.
Errors:
- You need to enter a positive numeric value (code 9999)
- Adding funds to the account balance is currently disabled (code 980)
- Amount must be at least 10 (code 981)
- Amount cannot exceed 1000 (code 982)
- You must have at least one active order before you can add funds so you cannot proceed at the current time! (code 9999) when the client has no currency yet
Authorized users need the View and pay invoices permission.
Example
Request parameters:
{ "amount": 50}result:
"a1b2c3d4e5f60718293a4b5c6d7e8f90"transaction_get_list (client)
Section titled “transaction_get_list (client)”POST /api/client/invoice/transaction_get_list
Lists the processed payments of the client’s invoices, newest first.
| Parameter | Type | Description |
|---|---|---|
invoice_hash |
string | Only this invoice’s payments. |
invoice_id |
integer | Only this invoice’s payments. |
gateway_id |
integer | Only this payment method. |
currency |
string | A currency code. |
type |
string | payment, refund, subscription_create, subscription_cancel or unknown. |
date_from |
string | Created at or after this date and time. |
date_to |
string | Created on or before this day (the whole day). |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, invoice_id, txn_id, txn_status, gateway_id, gateway, amount, currency, type, status, ip, validate_ipn, error, error_code, note, created_at and updated_at.
Authorized users need the View and pay invoices permission.
get_tax_rate (client)
Section titled “get_tax_rate (client)”POST /api/client/invoice/get_tax_rate
The tax rate (percent) that applies to the signed-in client: 0 when the client is not taxed.
No parameters.
Returns: The rate, such as "20" or 0.
Every authorized user may call it.
statement (client)
Section titled “statement (client)”POST /api/client/invoice/statement
The client’s account statement: invoices, payments and account credit with the running balance, in the client’s currency.
| Parameter | Type | Description |
|---|---|---|
from |
string | Start date (YYYY-MM-DD); earlier lines make the opening balance. |
to |
string | End date (YYYY-MM-DD). |
Returns: client (id, name, company, email), currency, from, to, opening, lines (each date, type (invoice, payment or credit), description, title, detail, debit, credit, balance, and invoice_id where there is one), debit, credit and closing. A negative balance means the client owes.
Errors:
- Enter the dates as year-month-day. (code 9999)
- The start date is after the end date. (code 9999)
Only issued invoices count; cancelled and refunded invoices are left out. Authorized users need the View and pay invoices permission.
statement_pdf (client)
Section titled “statement_pdf (client)”POST /api/client/invoice/statement_pdf
The client’s account statement as a PDF.
| Parameter | Type | Description |
|---|---|---|
from |
string | Start date (YYYY-MM-DD). |
to |
string | End date (YYYY-MM-DD). |
Returns: A PDF file, not JSON.
Authorized users need the View and pay invoices permission.
quote_get_list (client)
Section titled “quote_get_list (client)”POST /api/client/invoice/quote_get_list
Lists the client’s quotes that were sent (not drafts), newest first.
No parameters.
Returns: A list of quotes as in the admin quote_get, without admin_notes.
Authorized users need the View and accept quotes permission.
payment_details (client)
Section titled “payment_details (client)”POST /api/client/invoice/payment_details
The payment instructions (bank details) of a manual payment method for one of the client’s unpaid invoices. It changes nothing and is not rate-limited.
| Parameter | Type | Description |
|---|---|---|
hash |
string | The unpaid invoice’s hash. |
gateway_id |
integer | A manual payment method (Custom or one built on it). |
Returns: The instructions as HTML, or an empty string when the invoice is not this client’s unpaid invoice or the method is not a manual one.
Authorized users need the View and pay invoices permission.
receipt_send (client)
Section titled “receipt_send (client)”POST /api/client/invoice/receipt_send
Uploads the receipt of a manual payment (a bank transfer) for one of the client’s unpaid invoices. Staff get a support ticket with it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
gateway_id |
integer, required | The manual payment method used, which must take receipt uploads. |
receipt |
mixed, required | The file, sent as a multipart form field: a JPG, PNG or WebP image or a PDF, under 5 MB. |
Returns: The id of the support ticket opened.
Errors:
- Invoice not found (code 9999)
- This invoice is not waiting for payment. (code 9999)
- Choose a payment method that takes transfers. (code 9999)
- This payment method does not take receipt uploads. (code 9999)
- Choose the receipt file (an image or a PDF). (code 9999)
- The receipt must be smaller than 5 MB. (code 9999)
- The receipt must be a JPG, PNG or WebP image or a PDF. (code 9999)
The invoice stays unpaid until staff record the payment. Authorized users need the View and pay invoices permission.
card_list (client)
Section titled “card_list (client)”POST /api/client/invoice/card_list
The client’s saved payment methods for the Payment methods page: Stripe cards and bank accounts, PayPal, PayPal Auto-Pay, PayTabs, eWAY, GoCardless and Mollie.
No parameters.
Returns: auto_charge (false when staff turned Disable CC Processing on for the client: saved methods are not charged automatically), available (false without an enabled Stripe gateway), bank (whether a bank account can be saved at Stripe), cards (Stripe methods, each {id, card, default}), and paypal ({account, default}), autopay, paytabs, eway, gocardless and mollie (each {account, default, add}), or null when that gateway does not offer saved methods. default marks the method that pays the invoices; add says the client may set it up from this page.
Only the account owner may call it, not other authorized users.
Example
Request parameters:
{}result:
{ "available": true, "bank": false, "cards": [ { "id": "pm_1Example", "card": "Visa •••• 4242 (12/2028)", "default": true } ], "paypal": null, "autopay": null, "paytabs": null, "eway": null, "gocardless": null, "mollie": null}card_available (client)
Section titled “card_available (client)”POST /api/client/invoice/card_available
Whether any payment gateway offers saved cards or saved accounts here (for the client menu).
No parameters.
Returns: true or false.
Only the account owner may call it, not other authorized users.
paypal_default (client)
Section titled “paypal_default (client)”POST /api/client/invoice/paypal_default
Makes the saved PayPal account the method that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- Saved PayPal accounts are not available. (code 9999)
- You have no saved PayPal account. (code 9999)
Only the account owner may call it.
paypal_remove (client)
Section titled “paypal_remove (client)”POST /api/client/invoice/paypal_remove
Removes the client’s saved PayPal account.
No parameters.
Returns: true.
Errors:
- Saved PayPal accounts are not available. (code 9999)
Only the account owner may call it.
paypal_pay (client)
Section titled “paypal_pay (client)”POST /api/client/invoice/paypal_pay
Pays one of the client’s unpaid invoices now with the saved PayPal account.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}: whether it was paid, and PayPal’s reason when not.
Errors:
- Saved PayPal accounts are not available. (code 9999)
- You cannot pay this invoice with a saved PayPal account. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
Only the account owner may call it.
autopay_default (client)
Section titled “autopay_default (client)”POST /api/client/invoice/autopay_default
Makes the PayPal billing agreement (PayPal Auto-Pay) the method that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- Automatic payments with PayPal are not available. (code 9999)
- You have not set up automatic payments with PayPal. (code 9999)
Only the account owner may call it.
autopay_remove (client)
Section titled “autopay_remove (client)”POST /api/client/invoice/autopay_remove
Stops automatic payments with PayPal: the billing agreement is cancelled at PayPal.
No parameters.
Returns: true.
Errors:
- Automatic payments with PayPal are not available. (code 9999)
Only the account owner may call it.
autopay_pay (client)
Section titled “autopay_pay (client)”POST /api/client/invoice/autopay_pay
Pays one of the client’s unpaid invoices now with the PayPal billing agreement, when the gateway allows paying with it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}: whether it was paid, and the reason when not.
Errors:
- Automatic payments with PayPal are not available. (code 9999)
- You cannot pay this invoice with a saved PayPal account. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
It does not count as an automatic try and sends no email. Only the account owner may call it.
paytabs_default (client)
Section titled “paytabs_default (client)”POST /api/client/invoice/paytabs_default
Makes the card saved at PayTabs the method that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- PayTabs is not available. (code 9999)
- You have no card saved with PayTabs. (code 9999)
Only the account owner may call it.
paytabs_remove (client)
Section titled “paytabs_remove (client)”POST /api/client/invoice/paytabs_remove
Removes the card saved at PayTabs (it is deleted at PayTabs too).
No parameters.
Returns: true.
Errors:
- PayTabs is not available. (code 9999)
Only the account owner may call it.
paytabs_pay (client)
Section titled “paytabs_pay (client)”POST /api/client/invoice/paytabs_pay
Pays one of the client’s unpaid invoices now with the card saved at PayTabs, when the gateway allows it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}.
Errors:
- PayTabs is not available. (code 9999)
- You cannot pay this invoice with a saved card. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
Only the account owner may call it.
eway_default (client)
Section titled “eway_default (client)”POST /api/client/invoice/eway_default
Makes the card saved at eWAY the method that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- eWAY is not available. (code 9999)
- You have no card saved with eWAY. (code 9999)
Only the account owner may call it.
eway_remove (client)
Section titled “eway_remove (client)”POST /api/client/invoice/eway_remove
Removes the card saved at eWAY.
No parameters.
Returns: true.
Errors:
- eWAY is not available. (code 9999)
Only the account owner may call it.
eway_pay (client)
Section titled “eway_pay (client)”POST /api/client/invoice/eway_pay
Pays one of the client’s unpaid invoices now with the card saved at eWAY, when the gateway allows it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}.
Errors:
- eWAY is not available. (code 9999)
- You cannot pay this invoice with a saved card. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
Only the account owner may call it.
gocardless_default (client)
Section titled “gocardless_default (client)”POST /api/client/invoice/gocardless_default
Makes the Direct Debit set up with GoCardless the method that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- GoCardless is not available. (code 9999)
- You have no Direct Debit set up with GoCardless. (code 9999)
Only the account owner may call it.
gocardless_remove (client)
Section titled “gocardless_remove (client)”POST /api/client/invoice/gocardless_remove
Removes the Direct Debit set up with GoCardless (the mandate is cancelled at GoCardless).
No parameters.
Returns: true.
Errors:
- GoCardless is not available. (code 9999)
Only the account owner may call it.
gocardless_pay (client)
Section titled “gocardless_pay (client)”POST /api/client/invoice/gocardless_pay
Starts collecting one of the client’s unpaid invoices from their GoCardless Direct Debit, when the gateway allows it. A bank debit takes days to clear.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}.
Errors:
- GoCardless is not available. (code 9999)
- You cannot pay this invoice by Direct Debit. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
Only the account owner may call it.
mollie_default (client)
Section titled “mollie_default (client)”POST /api/client/invoice/mollie_default
Makes the method saved at Mollie the one that pays the client’s invoices.
No parameters.
Returns: true.
Errors:
- Mollie is not available. (code 9999)
- You have no payment method saved with Mollie. (code 9999)
Only the account owner may call it.
mollie_remove (client)
Section titled “mollie_remove (client)”POST /api/client/invoice/mollie_remove
Removes the method saved at Mollie.
No parameters.
Returns: true.
Errors:
- Mollie is not available. (code 9999)
Only the account owner may call it.
mollie_pay (client)
Section titled “mollie_pay (client)”POST /api/client/invoice/mollie_pay
Pays one of the client’s unpaid invoices now with the method saved at Mollie, when the gateway allows it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
Returns: {paid, message}.
Errors:
- Mollie is not available. (code 9999)
- You cannot pay this invoice with a saved card. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
Only the account owner may call it.
card_save_choice (client)
Section titled “card_save_choice (client)”POST /api/client/invoice/card_save_choice
Records the “Save this card” choice for a Stripe card payment of one of the client’s unpaid invoices.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The unpaid invoice’s hash. |
gateway_id |
integer, required | The enabled Stripe gateway. |
intent |
string, required | The Stripe payment id. |
save |
boolean | Keep the card for later payments. |
make_default |
boolean | Make it the card that pays the invoices. |
Returns: true.
Errors:
- Only the account owner can save a payment method. (code 9999)
- This invoice is already paid or cancelled. (code 9999)
- Saved cards are not available. (code 9999)
Only the account owner may call it.
card_setup (client)
Section titled “card_setup (client)”POST /api/client/invoice/card_setup
Starts adding a card (or bank account) at Stripe: returns what Stripe’s card form needs.
No parameters.
Returns: {client_secret, pub_key}: the Stripe setup’s client secret and the publishable key.
Errors:
- Saved cards are not available. (code 9999)
Only the account owner may call it. After Stripe confirms the setup, call card_added.
card_added (client)
Section titled “card_added (client)”POST /api/client/invoice/card_added
Keeps the card of a confirmed Stripe setup. It becomes the default when the client has none.
| Parameter | Type | Description |
|---|---|---|
setup_intent |
string, required | The Stripe setup id. |
Returns: true.
Errors:
- Saved cards are not available. (code 9999)
Only the account owner may call it.
card_default (client)
Section titled “card_default (client)”POST /api/client/invoice/card_default
Makes a saved Stripe card the one invoices are charged to.
| Parameter | Type | Description |
|---|---|---|
id |
string, required | The card id (cards[].id of card_list). |
Returns: true.
Errors:
- Saved cards are not available. (code 9999)
Only the account owner may call it.
card_remove (client)
Section titled “card_remove (client)”POST /api/client/invoice/card_remove
Removes a saved Stripe card (it is removed at Stripe too).
| Parameter | Type | Description |
|---|---|---|
id |
string, required | The card id. |
Returns: true.
Errors:
- Saved cards are not available. (code 9999)
Only the account owner may call it.
Guest calls
Section titled “Guest calls”get (guest)
Section titled “get (guest)”POST /api/guest/invoice/get
Returns an invoice by its link hash, as its public page shows it.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash (30 to 60 hexadecimal characters). |
Returns: The invoice object, as in the client get_list.
Errors:
- Invalid invoice hash (code 404)
- Invoice was not found (code 404)
- This invoice link has expired (code 403)
- You do not have permission to perform this action (code 403) when the invoice is not the signed-in client’s and access by link is off
- Rate limit exceeded. Please try again later. (code 429)
Open to the signed-in client who owns the invoice, staff with View invoices, and anyone with the link when Allow Access Without Authentication Using Invoice Hash is on in the Invoices settings (until the link expires). Except for the owner, it is limited to 10 calls an hour per IP address and 30 per invoice.
gateways (guest)
Section titled “gateways (guest)”POST /api/guest/invoice/gateways
Lists the enabled payment methods, in the order clients see them.
| Parameter | Type | Description |
|---|---|---|
format |
string | pairs for an object of id => name. |
Returns: A list of methods, each with id, code, title, allow_single, allow_recurrent, accepted_currencies and logo (logo, height, width); or with format pairs an object of id => name.
payment (guest)
Section titled “payment (guest)”POST /api/guest/invoice/payment
Starts paying an invoice with a payment method. The result is what the method needs to show: an HTML form or button, or a redirect.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash. |
gateway_id |
integer, required | An enabled payment method. |
auto_redirect |
boolean | Whether the method sends the payer on at once instead of showing a pay button (methods that support it). |
allow_subscription |
boolean | Default true: pay by subscription when the invoice and the method allow it. false forces a one-time payment. |
Returns: {type, service_url, subscription, result}, plus iframe for methods that return HTML. type is html or the method’s type; result is the HTML or the method’s data.
Errors:
- Invoice hash not passed. Missing param hash (code 810)
- Invalid invoice hash (code 4001)
- Payment method not found. Missing param gateway_id (code 811)
- Invoice not found (code 812)
- Payment method not found (code 813)
- Payment method not enabled (code 814)
- One-time payments are not enabled for the selected payment gateway (code 815)
- Rate limit exceeded. Please try again later. (code 429)
Who may pay is as in get. The chosen method becomes the invoice’s, with its fee. Except for the owner, limited to 10 calls an hour per IP address and per invoice.
choose_gateway (guest)
Section titled “choose_gateway (guest)”POST /api/guest/invoice/choose_gateway
Makes the payment method picked on the invoice page the invoice’s, with its fee.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash. |
gateway_id |
integer, required | The payment method. |
Returns: true.
Errors:
- Invalid invoice hash (code 4001)
- Invoice not found (code 812)
- Payment method not found (code 813)
- This invoice is already paid or cancelled. (code 9999)
- A payment for this invoice is still clearing. (code 9999)
Who may call it is as in payment, and it shares that call’s rate limit.
payment_details (guest)
Section titled “payment_details (guest)”POST /api/guest/invoice/payment_details
The transfer details of a manual payment method for an invoice link, without signing in.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash. |
gateway_id |
integer, required | A manual payment method. |
Returns: The instructions as HTML, or an empty string when the invoice is not unpaid or the method takes no transfers.
Errors:
- Invalid invoice hash (code 4001)
- Invoice not found (code 812)
- Rate limit exceeded. Please try again later. (code 429)
Who may call it is as in payment. Except for the owner, limited to 60 calls an hour per IP address and per invoice.
funds_enabled (guest)
Section titled “funds_enabled (guest)”POST /api/guest/invoice/funds_enabled
Whether clients may add funds to their account credit.
No parameters.
Returns: true or false.
pdf (guest)
Section titled “pdf (guest)”POST /api/guest/invoice/pdf
Returns an invoice as a PDF.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The invoice hash. |
Returns: A PDF file, not JSON.
Errors:
- Invalid invoice hash (code 4001)
- Invoice not found (code 9999)
- This invoice link has expired (code 403)
- Rate limit exceeded. Please try again later. (code 429)
Who may get it is as in get. Except for the owner, limited to 10 calls an hour per IP address and per invoice.
payment_methods (guest)
Section titled “payment_methods (guest)”POST /api/guest/invoice/payment_methods
The payment methods a client can use for an amount, with each method’s gateway fee and total, as the payment cards show them.
| Parameter | Type | Description |
|---|---|---|
amount |
number, required | The amount (0 or more). |
currency |
string, required | Three-letter currency code. |
hash |
string | An unpaid invoice in that currency: each total is then its balance with the method’s fee. |
subscribable |
boolean | Whether the payment can be a subscription (fills recurrent). |
taxed |
number | Without an invoice: the taxed part of the order before tax, for the tax of a taxed fee. |
Returns: A list, each id, code, title, manual, receipt (takes receipt uploads), converts, quote (a converted amount {currency, total, rate} or null), mark, tone, single, recurrent, fee, fee_terms (percent, fixed, taxable) and total.
Errors:
- Amount or currency is not valid. (code 9999)
quote_get (guest)
Section titled “quote_get (guest)”POST /api/guest/invoice/quote_get
Returns a quote by its link, as its page shows it (no staff notes).
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The quote’s link hash (40 hexadecimal characters). |
Returns: The quote as in the admin quote_get without admin_notes, plus mine (the signed-in client is the one it is for) and invoice_url (the invoice it made, for that client; else null).
Errors:
- Quote not found (code 404)
quote_accept (guest)
Section titled “quote_accept (guest)”POST /api/guest/invoice/quote_accept
Accepts a quote from its link: a prospect gets a client account, and the invoice is made, issued and emailed.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The quote’s link hash. |
Returns: true.
Errors:
- Quote not found (code 404)
- This quote is already accepted. (code 9999)
- This quote can no longer be accepted. (code 9999)
- This quote has expired. Please contact us for a new one. (code 9999)
- You do not have permission to do this. Ask the account owner for access. (code 403) for an authorized user without the quotes permission
- Rate limit exceeded. Please try again later. (code 429)
Limited to 30 calls an hour per IP address (shared with quote_decline and quote_pdf). The client’s activity log records the answer and the staff member who made the quote is emailed.
quote_decline (guest)
Section titled “quote_decline (guest)”POST /api/guest/invoice/quote_decline
Declines a quote from its link: it becomes lost.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The quote’s link hash. |
Returns: true.
Errors:
- Quote not found (code 404)
- This quote can no longer be declined. (code 9999)
- Rate limit exceeded. Please try again later. (code 429)
Limited as quote_accept. The staff member who made the quote is emailed.
quote_pdf (guest)
Section titled “quote_pdf (guest)”POST /api/guest/invoice/quote_pdf
Returns a quote as a PDF from its link.
| Parameter | Type | Description |
|---|---|---|
hash |
string, required | The quote’s link hash. |
Returns: A PDF file, not JSON.
Errors:
- Quote not found (code 404)
- Rate limit exceeded. Please try again later. (code 429)
Limited to 30 calls an hour per IP address, shared with the quote answers.

