Invoices

Base URL: $CONSUMER_API

List invoices for explicitly linked consumer accounts

Logs

GET /invoices

Pages the invoices of accounts linked to the caller, across tenants unless X-Tenant-ID selects one. Filter with account_id (which must be one of the caller's accounts) and status; pagination uses limit and after.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

account_idstring · query · optional

Restrict results to one linked consumer account.

Returns

200 Invoices authorized for this consumer identity

curl -X GET "$CONSUMER_API/invoices" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Invoices authorized for this consumer identity

Get an invoice authorized for the authenticated consumer

Logs

GET /invoices/{id}

Returns one invoice, including its lines and balance, when it belongs to an account linked to the caller. Invoices outside the caller's account scope return 404.

Parameters

idstring · path · required

Identifier of the invoice to return.

Returns

200 Invoice in an account linked to the authenticated consumer

Errors 404

curl -X GET "$CONSUMER_API/invoices/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Invoice in an account linked to the authenticated consumer

List consumer invoice notes

Logs

GET /invoices/{id}/notes

List the debit and credit notes of an invoice authorized for the authenticated consumer

Notes the server wrote carry reason_code and reason_params so clients word them in the reader's language; reason is the stored fallback.

Parameters

idstring · path · required

Identifier of the invoice whose debit and credit notes are listed; it must belong to an account linked to the caller.

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Notes of an invoice in an account linked to the authenticated consumer, oldest first

Errors 404

curl -X GET "$CONSUMER_API/invoices/{id}/notes" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Notes of an invoice in an account linked to the authenticated consumer, oldest first

Download one of the caller's invoices as PDF

Logs

GET /invoices/{id}/pdf

Renders the invoice as a PDF, with the tenant's payment instructions, when it belongs to an account linked to the caller. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 404 when the invoice is missing or outside the caller's scope.

Parameters

idstring · path · required

Invoice id

layoutstring · query · optional · default a4

Page format. mobile is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.

one of a4, mobile

Returns

200 PDF document

Errors 403 · 404

curl -X GET "$CONSUMER_API/invoices/{id}/pdf" \
  -H "Authorization: Bearer sk_test_..."
Response 200

PDF document

Dispute an invoice on one of the caller's accounts

Logs

POST /invoices/{id}/dispute

Records a required reason, and optionally the line item or charge code being contested, and returns the invoice with its dispute details. While the dispute is open the account is left out of cutoff and late-penalty runs until the utility resolves it. Disputing again replaces the earlier dispute details. The invoice must be on an account where the caller holds the invoice.read account permission, found across the caller's tenants unless X-Tenant-ID narrows the search; any other invoice returns 404. Disputing also needs the ticket.create permission on the invoice's account (a personal API key needs the ticket.create scope); without it the call returns 403. A blank reason, a void invoice, a line_item_id that is not on the invoice or an unknown body field returns 400.

Parameters

idstring · path · required

ID of the invoice to dispute; it must be on one of the caller's accounts.

X-Tenant-IDstring · header · optional

Narrow the invoice lookup to one of the caller's tenants.

Body application/json

reasonstring · required

Why the caller contests the invoice; blank or whitespace-only is refused.

line_item_idstring · optional

Optional line item being contested; it must be on the invoice.

charge_codestring · optional

Optional charge code being contested; defaults to the line item's charge code when line_item_id is given.

Returns

200 Invoice marked as disputed

Show attributes
idstring · required
tenant_idstring · required
invoice_numberstring · required
customer_idstring · required
customer_namestring · optional

Display name of the referenced customer. Omitted when unknown.

account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

meter_idstring · optional
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

billing_run_idstring · optional
consumption_idstring · optional
from_reading_idstring · optional
to_reading_idstring · optional
period_startstring (date-time) · required
period_endstring (date-time) · required
consumption_m3number · optional
tariff_version_idstring · optional
subtotal_centsinteger · optional
sanitation_centsinteger · optional
tax_centsinteger · optional
total_centsinteger · required
balance_centsinteger · required
reconciliation_centsinteger · optional
arrears_centsinteger · optional
amount_due_centsinteger · required
estimatedboolean · optional
estimate_reconciled_atstring (date-time) · optional
currencystring · required
statusstring · required

one of draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · required
issued_atstring (date-time) · required
paid_atstring (date-time) · optional
voided_atstring (date-time) · optional
void_reasonstring · optional
disputed_atstring (date-time) · optional
dispute_reasonstring · optional
written_off_atstring (date-time) · optional
written_off_centsinteger · optional
write_off_reasonstring · optional
line_itemsarray of object · optional

Invoice lines. A line the server words carries description_code (invoice_line.fixed_fee, invoice_line.volumetric_tier, invoice_line.minimum_top_up, invoice_line.sanitation, invoice_line.vat, invoice_line.reconciliation) and description_params (tier, from, to; percent); clients word the code and fall back to description. Lines named after a tariff's own charges have no code.

created_atstring (date-time) · required
updated_atstring (date-time) · required

Errors 400 · 401 · 403 · 404

curl -X POST "$CONSUMER_API/invoices/{id}/dispute" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "The meter reading on this invoice is higher than the meter shows.",
  "line_item_id": "lin_2UK5t48jnSYdLq0vr4Mh9kkthmC",
  "charge_code": "CHA-2026-000142"
}'
Response 200
{
  "id": "bil_2ddw83puA9dkmtvSYPhUgT7iqrb",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "invoice_number": "INV-2026-000142",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "customer_name": "Ana Matsinhe",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "account_number": "ACC-2026-000142",
  "account_holder_name": "Ana Matsinhe",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "meter_serial": "meter serial",
  "meter_holder_name": "Ana Matsinhe",
  "billing_run_id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "consumption_id": "con_2nR0I9tA6XXk4bxUyjPqmvxi8nN",
  "from_reading_id": "fro_2zXkivBGsXvOyvPqMFry433gEp5",
  "to_reading_id": "tor_2YMhF6MrDmIFLAyjLcYXv4YbHMe",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "consumption_m3": 13.42,
  "tariff_version_id": "tar_2TzCwDDsMdpa2HfkINTSsLvKunb",
  "subtotal_cents": 125000,
  "sanitation_cents": 1,
  "tax_cents": 1,
  "total_cents": 125000,
  "balance_cents": 125000,
  "reconciliation_cents": 1,
  "arrears_cents": 1,
  "amount_due_cents": 125000,
  "estimated": true,
  "estimate_reconciled_at": "2026-11-19T09:30:00Z",
  "currency": "MZN",
  "status": "draft",
  "due_date": "2026-11-19T09:30:00Z",
  "issued_at": "2026-11-19T09:30:00Z",
  "paid_at": "2026-11-19T09:30:00Z",
  "voided_at": "2026-11-19T09:30:00Z",
  "void_reason": "void reason",
  "disputed_at": "2026-11-19T09:30:00Z",
  "dispute_reason": "dispute reason",
  "written_off_at": "2026-11-19T09:30:00Z",
  "written_off_cents": 1,
  "write_off_reason": "write off reason",
  "line_items": [
    {}
  ],
  "created_at": "2026-11-19T09:30:00Z",
  "updated_at": "2026-11-19T09:30:00Z"
}