Skip to content

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.

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": []
}

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:

true

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"

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.

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.

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)

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:

44

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.

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:

true

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.

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.

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)

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.

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.

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.

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.

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.

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.

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)

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.

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)

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.

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.

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.

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.

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.

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.

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
}

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 (status error).

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 (status error).

Fires onBeforeAdminTransactionProcess and onAfterAdminTransactionProcess.

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.

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:

31

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.

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)

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"
}
]
}

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
}
]

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}.

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.

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.

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.

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.

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)

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.

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"}.

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"].

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.

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)

POST /api/admin/invoice/gateway_copy

Makes a disabled copy of a payment gateway with the same settings, named “ (Copy)”.

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)

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:

true

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)

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.

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.

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.

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.

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 id nor sid is sent
  • Subscription not found (code 9999)

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)

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.

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:

3

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)

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)

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.

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.

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."
}
}

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).

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).

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).

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).

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.

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.

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.

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."
}
}
}
}

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"
}

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.

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.

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
}

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:

5

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)

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.

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.

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)

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)

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.

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)

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.

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.

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)

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
}
]

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.

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.

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.

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)

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.

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.

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.

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}.

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)

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.

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)

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.

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.

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.

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.

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.

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"

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.

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.

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.

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.

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.

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.

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.

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: 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
}

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

POST /api/guest/invoice/funds_enabled

Whether clients may add funds to their account credit.

No parameters.

Returns: true or false.

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.

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)

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)

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.

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.

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.