Invoices API

All endpoints require authentication and invoices tool permissions.

Mapping Rules

List Mapping Rules

GET /api/invoices/mapping-rules

Permission: invoices:view

Response: { rules } — each rule includes service_type_name from joined service_types.

Upsert Mapping Rule

PUT /api/invoices/mapping-rules/:serviceTypeId

Permission: invoices:manage

Body:

Field	Type	Required	Description
`xero_account_code`	string	Yes	Xero account code to map to
`description`	string	No	Optional description

Response: { rule }

Invoices

List Invoices

GET /api/invoices

Permission: invoices:view

Query parameters:

Param	Type	Description
`status`	string	Filter by invoice status
`company_id`	string	Filter by company
`budget_id`	string	Filter by budget
`project_id`	string	Filter by project (via budget)
`deal_id`	string	Filter by deal (via budget)

Response: { invoices } — each invoice includes company_name, contact_name, and budget_name.

Create Invoice

POST /api/invoices

Permission: invoices:update

Body:

Field	Type	Required	Description
`budget_id`	string	No	Link to a budget
`invoice_number`	string	No	Custom invoice number (auto-generated if omitted)
`currency`	string	No	Currency code (default: `AUD`)
`due_date`	string	No	Due date (YYYY-MM-DD)
`issued_date`	string	No	Issue date (defaults to today)
`notes`	string	No	Free-text notes
`company_id`	string	No	Company ID
`contact_id`	string	No	Contact ID
`generate_from_budget`	boolean	No	Auto-generate line items from budget

When generate_from_budget is true, line item generation depends on the budget type:

Sprints / Retainer: copies budget line items at their fixed amounts. Retainer budgets can only be invoiced once.
Time & Materials: invoices only approved, uninvoiced time per line item.
Fixed Price: invoices the remaining uninvoiced amount as a single line item.

Tax is calculated at 10% GST. Auto-completes client onboarding milestone first_invoice for the company’s first invoice.

Response: { invoice } (201)

Get Invoice Detail

GET /api/invoices/:id

Permission: invoices:view

Response: { invoice, line_items, payments }

The invoice includes company_name, contact_name, budget_name, project_name, project_id, po_number, xero_status, and xero_url. If linked to Xero, the status is synced live from Xero on each request.

Update Invoice

PUT /api/invoices/:id

Permission: invoices:update

Body: Any of the following fields:

Field	Type	Description
`invoice_number`	string	Invoice number
`status`	string	Invoice status
`currency`	string	Currency code
`due_date`	string	Due date
`issued_date`	string	Issue date
`notes`	string	Notes
`company_id`	string	Company ID
`contact_id`	string	Contact ID
`budget_id`	string	Budget ID
`xero_invoice_id`	string	Xero invoice ID

Response: { invoice }

Delete Invoice

DELETE /api/invoices/:id

Permission: invoices:manage

If linked to Xero, the invoice is deleted (if DRAFT) or voided (if AUTHORISED+) in Xero before local deletion.

Response: { ok: true }

Xero Integration

Push to Xero

POST /api/invoices/:id/push-to-xero

Permission: invoices:update

Creates a DRAFT invoice in Xero from the local invoice and line items. Uses the company name as the Xero contact, and maps line item account codes from mapping rules. Sets local status to finalised.

Response: { invoice, xero_invoice_id }

Approve in Xero

POST /api/invoices/:id/xero-approve

Permission: invoices:manage

Transitions a Xero DRAFT invoice to AUTHORISED. Sets local status to approved.

Response: { invoice }

Send via Xero

POST /api/invoices/:id/xero-send

Permission: invoices:manage

Sends an AUTHORISED Xero invoice via email. Sets local status to sent.

Response: { invoice }

Void in Xero

POST /api/invoices/:id/xero-void

Permission: invoices:manage

Voids the Xero invoice. Sets local status to voided.

Response: { invoice }

Delete from Xero

POST /api/invoices/:id/xero-delete

Permission: invoices:manage

Deletes the Xero invoice (DRAFT only). Clears the local Xero ID and resets status to draft.

Response: { invoice }

Download PDF from Xero

GET /api/invoices/:id/pdf

Permission: invoices:view

Downloads the invoice PDF from Xero. Returns application/pdf with Content-Disposition: attachment.

Sync All from Xero

POST /api/invoices/sync-xero

Permission: invoices:update

Batch syncs payment status, amounts paid/due, and individual payments for all Xero-linked invoices.

Response: { updated, errors, synced_at }

Sync Single from Xero

POST /api/invoices/:id/sync-xero

Permission: invoices:update

Syncs payment status and payments for a single Xero-linked invoice.

Response: { invoice, payments, xero_status, payment_status }

Line Items

Reorder Line Items

PUT /api/invoices/:id/line-items/reorder

Permission: invoices:update

Body:

Field	Type	Required	Description
`item_ids`	string[]	Yes	Ordered array of line item IDs

Response: { ok: true }

Add Line Item

POST /api/invoices/:id/line-items

Permission: invoices:update

Body:

Field	Type	Required	Description
`description`	string	Yes	Line item description
`quantity`	number	No	Quantity (default: 1)
`unit_price`	number	No	Unit price (default: 0)
`service_type_id`	string	No	Service type ID
`xero_account_code`	string	No	Xero account code
`tax_type`	string	No	Tax type
`position`	number	No	Sort position

Automatically recalculates invoice totals (subtotal, 10% GST, total).

Response: { item } (201)

Update Line Item

PUT /api/invoices/:id/line-items/:itemId

Permission: invoices:update

Body: Any of: description, quantity, unit_price, service_type_id, xero_account_code, tax_type, position.

Automatically recalculates line item amount and invoice totals.

Response: { item }

Delete Line Item

DELETE /api/invoices/:id/line-items/:itemId

Permission: invoices:update

Automatically recalculates invoice totals.

Response: { ok: true }