Issue invoices and credit notes
Issue a manual invoice on a service account outside a billing run, then lower or raise what it charges with a credit or debit note, and watch the invoice.issued and invoice.adjusted events.
What you will build#
Most invoices come from billing runs, which price accepted readings against the tariff. Some charges have no reading behind them: a reconnection fee, a damaged seal, a one-off service. In this guide you issue one of those by hand on an existing account, then correct it with a credit note. A manual invoice is numbered in the same gap-free series as run invoices, posted to the ledger and paid the same way, so nothing downstream has to treat it differently.
Prerequisites#
- A sandbox, whose sample data includes active accounts and the tariffs that price them.
- A test API key in
$API_KEYwithinvoices:write(issue and adjust),invoices:readandbusiness:accounts:read. The billing capability must be active for the utility, or the API answers403withcode: "CAPABILITY_INACTIVE". - Optional:
gotactlsigned in to the same sandbox, to watch the events.
1. Pick an account#
curl -sS "$BUSINESS_API/accounts?status=active&limit=1" \
-H "Authorization: Bearer $API_KEY"
2. Issue the manual invoice#
account_id and at least one entry in lines are required. Each line needs a description, a quantity above zero and a unit_price_cents of at least 1. Prices are in the currency of the account's active tariff. Set taxable: true on a line to charge VAT on it at that tariff's rate. customer_id is optional, but when you send it the customer must own the account. Without due_date, the invoice falls due after the billing policy's payment terms, or 30 days when the policy sets none.
curl -sS -X POST "$BUSINESS_API/invoices/manual" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: reconnection-act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3-2026-11" \
-H "Content-Type: application/json" \
-d '{"account_id":"act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3","lines":[{"description":"Reconnection after suspension","quantity":1,"unit_price_cents":150000,"taxable":false}]}'
{
"id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"invoice_number": "INV-000214",
"customer_id": "cus_2pN4vR8kTq1WmZ6xLc9BsH3dYf7",
"account_id": "act_2pN4wF6gLr2ZtB9uKe4WqP7hYc3",
"tariff_version_id": "trf_2nX6bT1rQp8LwK3vYm5ZcJ7sHd4",
"subtotal_cents": 150000,
"sanitation_cents": 0,
"tax_cents": 0,
"total_cents": 150000,
"balance_cents": 150000,
"amount_due_cents": 150000,
"currency": "MZN",
"status": "open",
"payment_terms_days": 30,
"issued_at": "2026-11-19T10:02:41Z",
"due_date": "2026-12-19T10:02:41Z",
"line_items": [
{
"id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5-1",
"invoice_id": "inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5",
"description": "Reconnection after suspension",
"quantity": 1,
"unit_price_cents": 150000,
"total_cents": 150000,
"line_type": "charge_component",
"component_kind": "fixed",
"taxable": false
}
]
}
3. Issue a credit note#
A credit note lowers the balance; a debit note raises both the balance and the total. type (credit_note or debit_note), a positive amount_cents and a reason are required. Only a debit note may carry category late_fee or interest; every note defaults to general.
curl -sS -X POST "$BUSINESS_API/invoices/inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5/adjust" \
-H "Authorization: Bearer $API_KEY" \
-H "Idempotency-Key: cn-inv_2pP8kM3xVt6RbN1qZw4HcY9fLd5-1" \
-H "Content-Type: application/json" \
-d '{"type":"credit_note","amount_cents":50000,"reason":"Reconnection done on the same day as the payment"}'
Test it#
Before step 2, start a listener in another terminal:
gotactl webhooks listen --events invoice.issued,invoice.adjusted --forward-to http://localhost:3000/hooks
Each step prints a line with --> invoice.issued or --> invoice.adjusted and your endpoint's status code. In the dashboard, open the invoice under Invoices; the Credit or debit note action issues the same note, and every note is listed under Credit and debit notes. GET $BUSINESS_API/invoices/{id}/pdf?locale=en-US renders the invoice as a PDF.