Issue a credit note against an invoice
POST/billing/invoices/:id/credit-notes
Creates a CreditNote for a partial-adjustment refund / correction against an existing invoice. Emits a balance-neutral negative-amount TaxPayable for the credited VAT portion so the URA-04 return nets to the correct value. Sequential reference per Tax Procedures Act §39 (CN-<YYYYMM>-<sequence>). Requires the invoice:credit_note:write permission.
Request
Responses
- 201
- 400
- 401
- 403
- 404
- 409
- 422
- 429
- 500
Newly-created CreditNote row.
Amount exceeds the invoice remaining balance or invoice already in a non-creditable state.
Missing or invalid access token.
Caller lacks the required permission.
Invoice not found.
The request conflicts with the current state of the target resource — a duplicate unique field on registration, an idempotency-key replay with a different payload, or a webhook eventId that has already been processed. error.code may be CONFLICT or IDEMPOTENCY_CONFLICT depending on the cause.
The request is syntactically valid but violates a business invariant — a referral state transition not permitted from the current status, a wallet withdrawal exceeding the available balance, or a POP being confirmed before it has been ZFA-verified. error.code is one of INVALID_TRANSITION, INVARIANT_VIOLATION, or a domain-specific value; error.message explains the invariant.
Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.
Response Headers
Seconds to wait before retrying.
Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.