Billing API overview

The Billing API manages the money side of running payroll for clients. You use it to maintain the clients you bill, issue and manage invoices, raise and allocate credit notes, keep your organisation’s finance settings (tax rates, account codes, templates, and defaults), and push documents to a connected accounting provider such as Xero. It backs the product features described in the clients and invoices and billing guides. All endpoints live under the /v1/billing base path, relative to the gateway base URLs listed in the API reference introduction. For example, the full sandbox URL for listing clients is https://api.sandbox.flowpayroll.ai/v1/billing/clients.

​

Key concepts

• Client — an entity your organisation bills for payroll services. Each client carries its own finance settings, and can be archived and later unarchived.
• Invoice — a bill raised against a client, made up of line items. Invoices move through Draft, Issued, Paid, and Voided statuses.
• Credit note — a document that reduces what a client owes. Credit notes are created in Draft status with line items and tax calculations, and move through Draft, Authorised, Paid, and Voided.
• Allocation — the application of an authorised credit note’s value against an invoice’s balance due.
• Tax rate — an organisation-level tax rate applied to line items. You create custom rates or import them from your connected provider, and archive rates you no longer use.
• Account code — an organisation-level ledger account that line items post to, managed and imported the same way as tax rates.
• Pay element mapping — an organisation-level mapping that determines the account code and tax treatment applied to invoice line items, and can be re-applied to draft invoices.
• Integration — a connection between your organisation and an accounting provider, established through OAuth or a custom connection. A connection can expose several tenants; you choose which one to sync with.

​

API structure

​

Clients

Manage clients under /clients: list, create, retrieve, update, and delete them, and restore an archived client with PATCH /clients/{clientId}/unarchive. Each client’s default tax rates and account codes live at /clients/{clientId}/finance-settings.

​

Invoices

List invoices for the organisation (GET /invoices) or for one client (GET /clients/{clientId}/invoices), and retrieve an invoice with its line items. Update or close an open invoice, issue draft invoices in bulk with POST /invoices/bulk-action, and email, void, or fully credit an issued invoice. You can also manage attachments and refresh a draft invoice’s line item mappings.

​

Credit notes

Create a draft credit note with POST /credit-notes, then update or delete it while it remains in Draft. Authorise it to make its credit available, allocate credit to invoices (or remove an allocation), void it, and manage attachments on drafts. List credit notes for the organisation or per client.

​

Tax rates and account codes

Maintain the organisation’s tax rates under /finance/tax-rates and account codes under /finance/accounts: list, create, update, delete, archive, and unarchive.

​

Finance defaults

Read and update organisation-wide finance defaults at /finance/finance-defaults and pay element mappings at /finance/pay-element-mappings. GET /finance/attachment-limits returns the attachment limits imposed by your connected provider.

​

Invoice and credit note templates

Read and update the organisation’s document templates at /finance/invoice-template and /finance/credit-note-template. Companion endpoints list the formula placeholders available for line item descriptions and invoice references.

​

Integrations

Connect an accounting provider under /integrations/{provider} using OAuth (login URI, callback, and code exchange) or a custom connection (save credentials, then test and save). List your connections and the provider’s tenants, switch the active tenant, and disconnect.

​

Accounting sync

Push a client and its contacts, an invoice, or a credit note to the connected provider with the /sync endpoints, and download the provider’s PDF of an invoice or credit note. To pull reference data the other way, list the provider’s tax rates, account codes, and contacts with the paginated provider-* endpoints, then import your selection with the import-from-provider endpoints.

​

Typical workflow

1. Connect your accounting provider under /integrations/{provider} and select the tenant to sync with.
2. Set up finance reference data: import tax rates and account codes from the provider, or create your own under /finance/tax-rates and /finance/accounts.
3. Configure your finance defaults, pay element mappings, and invoice and credit note templates under /finance.
4. Create clients with POST /clients, or import your provider’s contacts, and adjust each client’s finance settings.
5. Review draft invoices with GET /invoices, refresh their line item mappings if your mappings changed, then issue them with POST /invoices/bulk-action.
6. Send issued invoices to clients by email and push them to your provider with the sync endpoints.
7. Handle credits: create and authorise credit notes and allocate them to invoices, or credit an entire invoice in one call with POST /invoices/{clientId}/{invoiceId}/full-credit.

​

Notes and best practices

• Draft is the editable stage. Only Draft credit notes can be updated or deleted, attachments can only be added to draft credit notes, and only draft invoices can be issued or have their line item mappings refreshed.
• Only Issued invoices can be voided or fully credited. Voiding sets the balance due to zero; a full credit creates, authorises, and allocates a matching credit note, setting the invoice to Paid.
• Allocations are validated against both documents: the amount must not exceed the credit note’s remaining credit or the invoice’s balance due, and both update atomically.
• Bulk issue processes each invoice individually and aggregates successes and failures, so check the response for per-invoice results.
• Attachment endpoints return presigned upload URLs: create the attachment metadata first, then upload each file with a PUT to the returned upload URL.

​

Authentication

Every request needs an X-Auth-Token header, and multi-organisation credentials also send X-Org-Id — see Authentication. All responses use the shared envelope described in Response format.