Skip to main content
Driver billing turns a driver’s tolls (and other chargeable events) into invoices, then lets you finalize, collect, adjust, and credit them. Three resources are involved:
  • Billing Plans — the rate rules (charges) applied to an agreement’s tickets.
  • Driver Invoices — a billed statement for an agreement over a period.
  • Credit Notes — a credit issued against a finalized invoice.

​
Routing & scope

All endpoints live under /v2/ and are scoped to the authenticated user’s fleet. Routes derive the fleet from the authenticated user; you cannot request another fleet’s data.

​
Conventions

  • Money / quantities are decimal strings ("12.50"), not floats.
  • Timestamps are ISO-8601 (2026-05-16T14:03:00Z); dates are YYYY-MM-DD.
  • IDs are integers.
  • Pagination is limit/offset (limit, offset); list responses are wrapped in { "count", "next", "previous", "results" }.
  • Errors use the DRF format: field errors {"field": ["message"]}, general errors {"detail": "message"}.

​
Invoice lifecycle

Every invoice starts as a DRAFT and moves to one of two terminal statuses: FINALIZED and VOID are terminal. (Voiding a FINALIZED invoice is planned but not yet implemented — today only DRAFT invoices are voided.)

​
How invoices are created

The trigger records why an invoice was created. Every type starts as a DRAFT.

​
DRAFT stage

While DRAFT:
  • Fees are editable via adjust fee. Tickets are not directly editable.
  • Refresh (refresh) recalculates fees and pulls in any unbilled tickets. It is called before finalizing.
  • For AGREEMENT_ENDED invoices only, tickets that arrive while the invoice is in DRAFT are swallowed into it automatically.

​
Finalization

  • Automatic finalization waits for the plan’s grace period to end.
  • You can finalize manually at any time as an override, before the grace period ends.
Finalizing locks the invoice (immutable), sets total, and triggers PDF generation.

​
Payment status

payment_status (PENDING, SUCCEEDED, FAILED) is set manually via the payment status endpoint — there is no payment integration. is_overdue is a marker only; being overdue has no automatic consequence.

​
Plan snapshot

On creation, the invoice freezes a copy of the plan and its charges in plan_snapshot. Fees are computed from this snapshot, not the live plan, so later plan edits don’t change an existing invoice. Fee adjustments reference a charge by its 0-based charge_snapshot_index into plan_snapshot.charges.

​
Credit notes

A credit note credits a finalized invoice. The total must be greater than 0 and no more than the invoice balance (total − credited_amount). Create one via the invoice sub-route (POST /driver-invoices/{id}/credit-notes/); the resource itself supports read, void, and download.

​
Documents (PDF)

Invoice and credit-note PDFs are generated asynchronously. Poll the download action: The download action is the safe entry point because it triggers generation on the first call. Once pdf_status is COMPLETE, the pdf_file field on the object holds the same (time-limited) URL.

​
CSV export

GET /driver-invoices/export/?channel=email emails a CSV export (invoices, fees, tickets) in the background. channel must be email. All current list filters are honored, so the export mirrors the list query. It returns 200 immediately; the files are emailed, not returned in the response.