Guide: sync invoices and payments to accounting

HQ has built-in connectors for QuickBooks Online, QuickBooks Desktop, Xero, Exact and Holded.
Use this guide when you connect another accounting system, a data warehouse or an e-invoicing provider.

How invoices relate to reservations

Invoices live in the Invoices module, separate from reservations.

An invoice created from a reservation has item_type car_rental.reservations and item_id set to the reservation ID.

An invoice status is one of draft, sent, open, partial, paid, void or template.
A template invoice is the model of a recurring invoice, not a bill, so skip it.

An invoice type is invoice, credit_note or refund.
The list returns all three, so check type and book credit notes and refunds as reversals.
A credit note created by voiding an invoice names that invoice in original_invoice_id.

Each invoice has its own payments and refunds.

Step 1 - Read invoices

Invoices come newest issued_on first, 50 per page unless you send limit.

The response is the pagination object itself, without success (see Responses and pagination).

You can filter on issued_on (date) and on contact_id, contact_type, status, po_number, invoice_number and products.category_id (string).

Each invoice includes its customer in contact, its tax in tax_object, the amount still due in total_unpaid and its line items in product_invoice.

This list has no updated_since.
Sync by issued_on period, and read recent invoices again, paid ones included, because a refund can still be added and the invoice can be voided.
Voiding can create a credit note with the original invoice's issued_on, so read past periods again too.
GET /invoices/invoices/{id} returns one invoice under invoice.

Step 2 - Read payments

GET /invoices/invoices/{id}/payments lists the payments and refunds of one invoice, newest first, in pages.
Filter on type (payment or refund), method, contact_id or paid_on.

Step 3 - Record payments received in your system (optional)

To record a payment on one invoice, send paid_on, method, amount_paid and notes (all required) to POST /invoices/invoices/{id}/payments.

To spread one payment over a customer's unpaid invoices, send contact_type (contacts for customers), contact_id, paid_on, method, amount_paid and notes to POST /invoices/invoices/attach-payment.
HQ pays the customer's draft, sent and partial documents (credit notes and refunds included, open ones not), in no guaranteed order, until the amount runs out, and returns the invoices it paid under invoices.
Any amount left after every invoice is paid is not recorded, so compare it with the invoices returned.

Step 4 - Export e-invoices (optional)

When Settings > Invoices > E-Invoicing has the PEPPOL BIS 3 format enabled:

GET /invoices/invoices/e-invoices/peppol_bis_3 lists the invoices that can be exported, in pages.
It accepts updated_since and filters on issued_on, status and brand_id.
Only invoices linked to a reservation are listed; quotes, credit notes, refunds, voided and template invoices never are.

GET /invoices/invoices/e-invoices/peppol_bis_3/download?ids=101,102,103 returns a ZIP file with one document per invoice, for up to 50 IDs.
Invoices that could not be rendered are listed in SKIPPED-INVOICES.txt and SKIPPED-INVOICES.json inside the ZIP.
When none could be rendered, the response is JSON with "success": false, so check the content type before you save the file.

When the format is not enabled, both endpoints return 404.

Get notified

Ask your HQ administrator to add Invoice webhooks with the custom actions invoice_sent, invoice_paid and invoice_partially_paid (see Webhooks).
Invoices do not send an event on every change, so keep a daily sync as well.

Guide: sync invoices and payments to accounting

How invoices relate to reservations#

Step 1 - Read invoices#

Step 2 - Read payments#

Step 3 - Record payments received in your system (optional)#