# 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_KEY` with `invoices:write` (issue and adjust), `invoices:read` and `business:accounts:read`. The billing capability must be active for the utility, or the API answers `403` with `code: "CAPABILITY_INACTIVE"`.
- Optional: `gotactl` signed in to the same sandbox, to watch the events.

## 1. Pick an account

```bash
curl -sS "$BUSINESS_API/accounts?status=active&limit=1" \
  -H "Authorization: Bearer $API_KEY"
```

✓ Checkpoint: `data[0].id` starts with `act_` and `data[0].status` is `active`. Use that `id` as `account_id` below.

## 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.

```bash
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}]}'
```

```json
{
  "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
    }
  ]
}
```

✓ Checkpoint: `201` with `status: "open"`, an `invoice_number` from the invoice series and `amount_due_cents` equal to `total_cents`. If the account holds unused credit, it is applied at once and `balance_cents` comes back lower.

## 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`.

```bash
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"}'
```

✓ Checkpoint: `200` with the updated invoice: `balance_cents` is `100000` and `status` is still `open`. A credit that reaches zero marks the invoice `paid`. A credit larger than the balance only takes it to zero; the `invoice.adjusted` event reports the part that was not applied as `credit_excess_minor`. Void and written-off invoices refuse notes, and a paid invoice accepts only credits; each of these returns `400`.

## Test it

Before step 2, start a listener in another terminal:

```bash
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.

## Next steps

- [Collect payment on the open invoice](/docs/guides/receive-payments)
- [Verify the signature on invoice events](/docs/webhooks/verify)
- [Every invoice operation in the Business API reference](/docs/api/business)

