PT EN

Facturas

URL base: $BUSINESS_API

O objecto

resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Listar facturas

Registos

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.

Parâmetros

limitinteger · consulta · opcional

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

afterstring · consulta · opcional

Opaque cursor returned by the previous page.

qstring · consulta · opcional

Resource-specific text search.

reading_idstring · consulta · opcional

Only invoices that opened or closed on this reading

Devolve

200 Invoices in the authenticated utility tenant

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Invoices in the authenticated utility tenant

Emitir uma factura

Registos

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.

Corpo application/json

customer_idstring · obrigatório

Customer the invoice is addressed to.

account_idstring · obrigatório

Account the invoice is billed to.

meter_idstring · opcional

Meter whose consumption is billed.

billing_run_idstring · opcional

Billing run to attach the invoice to.

consumption_idstring · opcional

Consumption record the volume comes from.

from_reading_idstring · opcional

Reading that opens the billed period.

to_reading_idstring · opcional

Reading that closes the billed period.

period_startstring (date-time) · opcional

Start of the billed period.

period_endstring (date-time) · opcional

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

consumption_m3number · opcional

Volume to price, in cubic metres.

tariff_version_idstring · opcional

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

due_datestring (date-time) · opcional

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

Devolve

201 The issued invoice

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

Permissões invoices:write · Funções: 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"
}'
Resposta 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"
}

Reconciliar o consumo de uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

new_consumption_idstring · obrigatório
new_consumption_m3number · obrigatório
from_reading_idstring · opcional
to_reading_idstring · opcional
reasonstring · obrigatório

Devolve

200 Invoice reconciled with credit or debit adjustment

Mostrar atributos
invoiceobject · obrigatório
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório
adjustmentobject · opcional
Mostrar atributos filhos
idstring · obrigatório
tenant_idstring · obrigatório
note_numberstring · opcional
invoice_idstring · obrigatório
account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

typestring · obrigatório

um de credit_note, debit_note

amount_centsinteger · obrigatório
reasonstring · obrigatório
approved_bystring · obrigatório
categorystring · opcional

um de general, late_fee, interest

created_atstring (date-time) · obrigatório
delta_centsinteger · obrigatório

Erros 400 · 403 · 404

Permissões invoices:write · Funções: 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."
}'
Resposta 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
}

Emitir uma factura manual

Registos

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.

Corpo application/json

account_idstring · obrigatório
customer_idstring · opcional

When given

due_datestring (date-time) · opcional

Defaults to the billing policy's payment terms

linesarray of object · obrigatório
Mostrar atributos filhos
descriptionstring · obrigatório
quantitynumber · obrigatório
unit_price_centsinteger (int64) · obrigatório
taxableboolean · opcional · predefinição false

Devolve

201 The issued invoice

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 403 · 404

Permissões invoices:write · Funções: 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
    }
  ]
}'
Resposta 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"
}

Ajustar uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

typestring · obrigatório

um de credit_note, debit_note

amount_centsinteger (int64) · obrigatório
reasonstring · obrigatório
categorystring · opcional

um de general, late_fee, interest

Devolve

200 Invoice with the applied adjustment

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Permissões invoices:write · Funções: 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"
}'
Resposta 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"
}

Obter os metadados de uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 404

Permissões business:metadata:read · Funções: admin, customer_service, owner

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

Actualizar os metadados de uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

metadataobject · obrigatório

Devolve

200 Resulting metadata

Mostrar atributos
resource_typestring · opcional
resource_idstring · opcional
metadataobject · opcional

Erros 400 · 404

Permissões business:metadata:write · Funções: admin, owner

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

Descarregar uma factura em PDF

Registos

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.

Parâmetros

idstring · caminho · obrigatório

Invoice id

layoutstring · consulta · opcional · predefinição a4

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

um de a4, mobile

Devolve

200 PDF document

Erros 403 · 404

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

PDF document

Abater o saldo de uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

reasonstring · opcional

Devolve

200 Success

Erros 400 · 403 · 404 · 409

Permissões invoices:write · Funções: 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."
}'
Resposta 200

Success

Contestar uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

reasonstring · obrigatório
line_item_idstring · opcional
charge_codestring · opcional

Devolve

200 Invoice marked as disputed

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 403 · 404

Permissões invoices:write · Funções: 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"
}'
Resposta 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"
}

Resolver a contestação de uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Invoice dispute resolved

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 403 · 404

Permissões invoices:write · Funções: admin, billing_clerk, finance, owner

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

Obter uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Devolve

200 Invoice

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

Permissões invoices:read · Funções: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

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

Anular uma factura

Registos

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.

Parâmetros

idstring · caminho · obrigatório

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

Corpo application/json

reasonstring · obrigatório

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

Devolve

200 The voided invoice

Mostrar atributos
idstring · obrigatório
tenant_idstring · obrigatório
invoice_numberstring · obrigatório
customer_idstring · obrigatório
customer_namestring · opcional

Display name of the referenced customer. Omitted when unknown.

account_idstring · obrigatório
account_numberstring · opcional

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

account_holder_namestring · opcional

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

meter_idstring · opcional
meter_serialstring · opcional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · opcional

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

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

um de draft, open, paid, partially_paid, void, uncollectible

due_datestring (date-time) · obrigatório
issued_atstring (date-time) · obrigatório
paid_atstring (date-time) · opcional
voided_atstring (date-time) · opcional
void_reasonstring · opcional
disputed_atstring (date-time) · opcional
dispute_reasonstring · opcional
written_off_atstring (date-time) · opcional
written_off_centsinteger · opcional
write_off_reasonstring · opcional
line_itemsarray of object · opcional

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) · obrigatório
updated_atstring (date-time) · obrigatório

Erros 400 · 401 · 403 · 404

Permissões invoices:write · Funções: 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"
}'
Resposta 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"
}