🚧
Future Release
The Billing API is currently in development and is not yet available for production use. These endpoints are provided for planning and development purposes only.

Bill API Overview

The Bill API provides comprehensive functionality for managing billing operations within Flow Payroll. This API enables you to handle client management, invoice generation, and billing workflows.

Key Features

Client Management: Create, retrieve, update, delete, and unarchive clients; manage client finance settings (tax rates, account codes)
Invoices: List, retrieve, update (e.g. tags), close, void, and bulk-issue invoices; manage attachments and line items; refresh line item mappings on draft invoices; credit entire invoices
Credit Notes: Create, update, authorise, void, and allocate credit notes to invoices; list line items and manage attachments on draft credit notes
Finance Settings: Organisation-level tax rates and account codes (list, create, update, delete, archive, unarchive) for credit note line items
Accounting Sync: Push client and contacts, invoices, and credit notes to a connected provider; download external PDFs; list and import tax rates, account codes, and contacts from the provider
Integrations: OAuth and custom-connection flows for accounting providers; list connections, tenants, and switch tenant
Billing Workflows: Streamline your billing processes with automated operations

API Structure

Clients

Manage organizations or entities that receive invoices for payroll and related services. Client endpoints support full CRUD, archiving/unarchiving, and finance settings (tax rates, account codes) per client.

Invoices

List invoices (by organisation or by client), retrieve details and line items, update open invoices (e.g. tags), close or void invoices, add/remove attachments, refresh line item mappings on draft invoices, bulk-issue draft invoices, and credit entire invoices.

Credit Notes

Create draft credit notes with line items and tax; list line items (paginated); add/delete attachments on draft credit notes; authorise, void, allocate credit to invoices, and remove allocations. List by organisation or by client.

Finance Settings

Organisation-level tax rates and account codes (list, create, update, delete, archive, unarchive). Used for credit note line item dropdowns and client finance settings.

Accounting Sync

Push client and contacts, invoices, and credit notes to the connected accounting provider; download invoice or credit note PDFs from the provider; list and import tax rates, account codes, and contacts from the provider (paginated list, then import selected items).

Integrations

Connect accounting providers via OAuth or custom (client_credentials) connection: get login URI, handle callback or exchange code, save credentials, list connections and tenants, switch tenant, disconnect.

Getting Started

Before using the Bill API, ensure you have:

Authentication: Valid API credentials (refer to Getting Started)
Client Setup: Created at least one client record for billing operations
API Access: Appropriate permissions for billing operations

Common Workflows

Setting Up a New Client

Create a client using the Create Client endpoint
Optionally configure client finance settings (tax rates, account codes)
Configure billing preferences and settings

Managing Invoices

List invoices for the organisation or for a specific client
Retrieve invoice details and line items; add attachments if needed
Update open invoices (e.g. add or change tags)
Issue draft invoices (single or bulk), then close or void as needed
Optionally credit an entire invoice or allocate credit notes to invoices

Credit Notes and Allocations

Create a draft credit note with line items; update or delete while in DRAFT
Authorise the credit note to make it available for allocation
Allocate credit to one or more invoices (or use Credit entire invoice on an invoice)
Remove allocations or void the credit note if needed

Rate Limits and Best Practices

Use pagination when retrieving large lists of clients or invoices
Implement proper error handling for failed operations
Cache client data when appropriate to reduce API calls
Use the appropriate HTTP methods for each operation

Support

For questions or issues with the Bill API, please refer to the main documentation or contact support.