Invoices

Base URL: $BUSINESS_API

The object

resource_typestring · optional
resource_idstring · optional
metadataobject · optional

List utility invoices

Logs

GET /invoices

Pages the invoices of the caller's tenant with limit (default 20, max 100) and the after cursor. Filter by customer_id, account_id, meter_id, reading_id, billing_run_id and status. q searches the invoice number and the accounts whose holder matches the text. Needs the invoices:read permission.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

qstring · query · optional

Resource-specific text search.

reading_idstring · query · optional

Only invoices that opened or closed on this reading

Returns

200 Invoices in the authenticated utility tenant

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Invoices in the authenticated utility tenant

Price consumption against a tariff and issue an invoice

Logs

POST /invoices

Issues one invoice for an account outside a billing run by pricing consumption_m3 for the period against a tariff version: tariff_version_id when given, otherwise the residential tariff active at period_end. Fixed charges, tiers, sanitation, extra charge components and tax are computed by the server, the invoice is numbered in the tenant's invoice series and opened with the tariff's currency, and the tenant's enabled payment instructions are copied onto it. Without due_date the invoice is due after the billing policy's default due days (30 when unset). Any account credit available is applied straight away, so the returned balance can be lower than the total. For an invoice made of free-text lines use POST $BUSINESS_API/invoices/manual instead. Requires invoices:write and the billing capability. customer_id and account_id are required and period_end must not be before period_start (400); unknown fields are rejected (400); no matching tariff returns 404.

Body application/json

customer_idstring · required

Customer the invoice is addressed to.

account_idstring · required

Account the invoice is billed to.

meter_idstring · optional

Meter whose consumption is billed.

billing_run_idstring · optional

Billing run to attach the invoice to.

consumption_idstring · optional

Consumption record the volume comes from.

from_reading_idstring · optional

Reading that opens the billed period.

to_reading_idstring · optional

Reading that closes the billed period.

period_startstring (date-time) · optional

Start of the billed period.

period_endstring (date-time) · optional

End of the billed period; must not be before period_start. Also picks the active tariff when tariff_version_id is omitted.

consumption_m3number · optional

Volume to price, in cubic metres.

tariff_version_idstring · optional

Tariff version to price with; defaults to the residential tariff active at period_end.

due_datestring (date-time) · optional

Due date; defaults to the billing policy's default due days after issue (30 when unset).

Returns

201 The issued invoice

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

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "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": 12.5,
  "tariff_version_id": "tar_2TzCwDDsMdpa2HfkINTSsLvKunb",
  "due_date": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "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"
}

Reconcile finalized invoice when a reading was superseded

Logs

POST /invoices/{id}/reconcile-consumption

Re-prices an invoice with the consumption that replaced a superseded reading, using the invoice's own tariff version and period. It stores the new consumption ID, the volume and, when given, the readings. Any difference from the old total is posted as a debit note (higher) or a credit note (lower), and the response reports delta_cents with the updated invoice. new_consumption_id and reason are required and new_consumption_m3 must not be negative; a void invoice returns 400. Needs the invoices:write permission.

Parameters

idstring · path · required

ID of the finalized invoice to reconcile; it must belong to the caller's tenant.

Body application/json

new_consumption_idstring · required
new_consumption_m3number · required
from_reading_idstring · optional
to_reading_idstring · optional
reasonstring · required

Returns

200 Invoice reconciled with credit or debit adjustment

Show attributes
invoiceobject · required
Show child 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
adjustmentobject · optional
Show child attributes
idstring · required
tenant_idstring · required
note_numberstring · optional
invoice_idstring · required
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.

typestring · required

one of credit_note, debit_note

amount_centsinteger · required
reasonstring · required
approved_bystring · required
categorystring · optional

one of general, late_fee, interest

created_atstring (date-time) · required
delta_centsinteger · required

Errors 400 · 403 · 404

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/reconcile-consumption" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "new_consumption_id": "new_2s2NZaaPts2fTWsFxKYhzQGXJim",
  "new_consumption_m3": 13.42,
  "from_reading_id": "fro_2zXkivBGsXvOyvPqMFry433gEp5",
  "to_reading_id": "tor_2YMhF6MrDmIFLAyjLcYXv4YbHMe",
  "reason": "Leitura confirmada no local."
}'
Response 200
{
  "invoice": {
    "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"
  },
  "adjustment": {
    "id": "bil_2pRmeP90Uttk4Z9EqFBauPLM6vB",
    "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
    "note_number": "NOT-2026-000142",
    "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
    "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
    "account_number": "ACC-2026-000142",
    "account_holder_name": "Ana Matsinhe",
    "type": "credit_note",
    "amount_cents": 125000,
    "reason": "Leitura confirmada no local.",
    "approved_by": "approved by",
    "category": "general",
    "created_at": "2026-11-19T09:30:00Z"
  },
  "delta_cents": 1
}

Issue a manual invoice with free lines for one account

Logs

POST /invoices/manual

Issues one invoice outside a billing run, numbered in the same gap-free invoice series and posted to the ledger like any other. Prices are in the currency of the account's active tariff; taxable lines carry VAT at that tariff's rate. Needs the invoices:write scope and the billing capability.

Body application/json

account_idstring · required
customer_idstring · optional

When given

due_datestring (date-time) · optional

Defaults to the billing policy's payment terms

linesarray of object · required
Show child attributes
descriptionstring · required
quantitynumber · required
unit_price_centsinteger (int64) · required
taxableboolean · optional · default false

Returns

201 The issued invoice

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 · 403 · 404

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/manual" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
  "customer_id": "cus_2UuXtOGTHWKlvkoF5so5Joi3Hck",
  "due_date": "2026-11-19T09:30:00Z",
  "lines": [
    {
      "description": "Leitura confirmada no local.",
      "quantity": 1,
      "unit_price_cents": 125000,
      "taxable": false
    }
  ]
}'
Response 201
{
  "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"
}

Post a credit or debit adjustment to an invoice

Logs

POST /invoices/{id}/adjust

Issues a credit_note or debit_note for a positive amount_cents with a required reason, and returns the updated invoice. A credit lowers the balance (any amount beyond it is kept as credit excess) and marks the invoice paid when the balance reaches zero. A debit raises both the balance and the total and may carry the category late_fee or interest (default general). Void and written-off invoices refuse notes, and paid invoices accept only credits; these state errors return 400. A note that moves money raises an invoice.adjusted event.

Parameters

idstring · path · required

ID of the invoice the credit or debit note applies to; it must belong to the caller's tenant.

Body application/json

typestring · required

one of credit_note, debit_note

amount_centsinteger (int64) · required
reasonstring · required
categorystring · optional

one of general, late_fee, interest

Returns

200 Invoice with the applied adjustment

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

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/adjust" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "type": "credit_note",
  "amount_cents": 125000,
  "reason": "Leitura confirmada no local.",
  "category": "general"
}'
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"
}

Get the metadata of a invoice

Logs

GET /invoices/{id}/metadata

Returns the free-form key-value metadata stored on an invoice of the caller's tenant, as a map of string keys to string values. Needs the business:metadata:read scope. Returns 404 when the invoice does not exist in this tenant.

Parameters

idstring · path · required

ID of the invoice whose metadata is read, up to 120 characters; it must belong to the caller's tenant.

Returns

200 Metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 404

Permissions business:metadata:read · Roles: admin, customer_service, owner

curl -X GET "$BUSINESS_API/invoices/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Merge metadata

Logs

PUT /invoices/{id}/metadata

Merge metadata; an empty value deletes the key

Merges the keys in the metadata object into what the invoice already carries, leaving other keys untouched, and returns the full resulting map. Keys are up to 40 characters with no square brackets or control characters, and values are up to 500 characters. A request may set at most 50 keys, and a merge that would leave more than 50 keys on the invoice is refused. Needs the business:metadata:write scope; 404 when the invoice is not in this tenant.

Parameters

idstring · path · required

ID of the invoice whose metadata is merged, up to 120 characters; it must belong to the caller's tenant.

Body application/json

metadataobject · required

Returns

200 Resulting metadata

Show attributes
resource_typestring · optional
resource_idstring · optional
metadataobject · optional

Errors 400 · 404

Permissions business:metadata:write · Roles: admin, owner

curl -X PUT "$BUSINESS_API/invoices/{id}/metadata" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "key": "value"
  }
}'
Response 200
{
  "resource_type": "resource type",
  "resource_id": "res_2iAXhMsJzmqPnY6X5cMTJ6OBTSG",
  "metadata": {
    "key": "value"
  }
}

Download an invoice as a Portuguese PDF factura

Logs

GET /invoices/{id}/pdf

Renders the invoice as an inline application/pdf document. It includes the issuer, the customer, the period, consumption, totals, previous balance, amount due and the payment instructions captured when the invoice was issued (or the tenant's current payment channels when none were captured). The query parameter locale (pt-MZ or en-US) picks the language, falling back to the caller's own locale and then pt-MZ. layout=mobile renders a phone-sized page instead of A4. Returns 404 when the invoice is not in the caller's tenant.

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

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

PDF document

Write off an unpaid balance as bad debt

Logs

POST /invoices/{id}/write-off

Moves the whole outstanding balance into written_off_cents, sets the balance to zero, marks the invoice uncollectible and stores the required reason. An invoice.written_off event posts the amount to bad debt expense in the ledger. An invoice with no balance left returns 400. Once written off, the invoice accepts no further credit or debit notes. Needs the invoices:write permission.

Parameters

idstring · path · required

ID of the invoice whose unpaid balance is written off; it must belong to the caller's tenant.

Body application/json

reasonstring · optional

Returns

200 Success

Errors 400 · 403 · 404 · 409

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/write-off" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local."
}'
Response 200

Success

Dispute invoice

Logs

POST /invoices/{id}/dispute

Mark an invoice as disputed, excluding the account from cutoff

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. Disputing again replaces the earlier dispute details. A void invoice cannot be disputed (400), and a line_item_id that is not on the invoice returns 400.

Parameters

idstring · path · required

ID of the invoice to mark as disputed; it must belong to the caller's tenant.

Body application/json

reasonstring · required
line_item_idstring · optional
charge_codestring · optional

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 · 403 · 404

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/dispute" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Leitura confirmada no local.",
  "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"
}

Lift a dispute

Logs

POST /invoices/{id}/dispute/resolve

Clears the open dispute on an invoice, stores the optional resolution text with the resolution time, and returns the invoice. The account becomes eligible for cutoff and late penalties again. The body may be empty. An invoice that is not under dispute returns 400. Needs the invoices:write permission.

Parameters

idstring · path · required

ID of the disputed invoice; it must belong to the caller's tenant.

Returns

200 Invoice dispute resolved

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 · 403 · 404

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/dispute/resolve" \
  -H "Authorization: Bearer sk_test_..."
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"
}

Get one invoice with its lines

Logs

GET /invoices/{id}

Returns one invoice of the caller's tenant with its amounts in minor units (subtotal, sanitation, tax, total, balance and amount due), status, period, due date, the payment instructions captured when it was issued, any void, dispute or write-off details, and its line items. Account, customer and meter references carry the holder's display name. Requires invoices:read; an id that does not exist in the caller's tenant returns 404.

Parameters

idstring · path · required

Identifier of the invoice (inv_...), matched within the caller's tenant only.

Returns

200 Invoice

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

Permissions invoices:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/invoices/{id}" \
  -H "Authorization: Bearer sk_test_..."
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"
}

Void an unpaid invoice

Logs

POST /invoices/{id}/void

Cancels an invoice that has no payments applied. The invoice keeps its number, so the series stays without gaps; its status becomes void, its balance drops to zero, voided_at and void_reason are set, an invoice.voided event and a status transition are recorded, and any account credit that had been applied to it is released back to the account. A non-empty reason is required. An invoice that is already void, or that is paid or partially paid, is refused with 400: correct those with a credit note or a payment reversal instead. Requires invoices:write; an unknown invoice returns 404.

Parameters

idstring · path · required

Identifier of the invoice to void, matched within the caller's tenant only.

Body application/json

reasonstring · required

Why the invoice is voided; stored on the invoice and in its history.

Returns

200 The voided invoice

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

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/invoices/{id}/void" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Issued to the wrong account"
}'
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"
}