Fiscal numbering & immutability

Tax authorities require invoice numbers to be sequential with no gaps — a missing number looks like a hidden, suppressed invoice. TaxLens allocates each number from a dedicated counter scoped to:

(issuer, document_type, series, fiscal_year)
//  e.g. (issuer 7, "380", "A", 2026) → 145, 146, 147, …
//       (issuer 7, "381", "C", 2026) → 31, 32, …      (credit notes)
//       (issuer 7, "389", "S", 2026) → 12, 13, …      (self-billed)

The number is burned at the moment of issuance by the issuer's sequence service, inside a lock on the booking, so two concurrent issue calls can never claim the same number or skip one. Each document type has its own counter, and the fiscal year rolls the sequence over.

The invoice date (BT-2) and the fiscal-year key are stamped in the issuer's local time, not the server's. An invoice issued late on 31 December in one timezone must not land in the next year's sequence just because the server is on UTC. TaxLens maps the issuer's country to a representative timezone for this.

Once a live issued invoice (380 or 389) exists for a booking, the issued document is immutable and the booking is frozen. Every path that would change the underlying numbers refuses:

A booking whose only invoice is credited or cancelled can again be voided, refunded, or have its invoice details edited — but it cannot be re-issued under the same primary document type. The credited row still occupies the (booking_id, document_type) slot, so a second 380 on that booking returns 409 ("re-issuance is not supported"). To put out a corrected invoice, credit the original, then issue a fresh one against a new booking. (The other primary type stays free — a credited 389 leaves the 380 slot open.) The full path is in The invoice lifecycle.

You never edit an issued invoice. To correct or cancel one, issue a credit note (381). It:

• draws its own number from the 381 counter (its own series);
• references the original invoice number (BT-25) and links it via preceding_invoice_id;
• reverses the original's amounts;
• marks the original credited, releasing the booking freeze on void / refund / invoice-details (a corrected invoice goes out against a new booking — the credited slot can't be re-issued).

In the UBL output a 381 (and 396) serializes as a PEPPOL CreditNote root, not an Invoice. A credit note is idempotent — one per booking.

curl -X POST https://api.taxlens.getdynamiq.ai/v1/invoices/9102/credit-note \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Stay shortened by one night" }'

# → 201  (381 referencing invoice 9102 / number A-2026-000145; replay → 200)
# {
#   "id": 9118,
#   "document_type": "381",
#   "invoice_number": "C-2026-000031",
#   "preceding_invoice_id": 9102,
#   "status": "issued"
# }

Browse, retrieve, and download every issued document — invoices, credit notes, and self-billed — in the Invoices dashboard. For the self-billed counter specifically, see Self-billing (389), and for idempotency semantics across the API, Errors & idempotency.