Credit notes

A credit note is an accounting document that reduces the amount a customer owes on a finalised invoice (or refunds them, if they’ve already paid). Once an invoice is open, you cannot edit it — you issue a credit note instead.

When credit notes happen

Trigger	Outcome
Refunding a paid invoice	A credit note is issued for the refunded amount; cash is refunded via the original payment method.
Voiding open lines on a partially-paid invoice	A credit note reduces amount_due.
Subscription downgrade with proration_behavior: create_prorations	A credit note is added as a negative line on the next invoice.
Late usage event with late_events: rebill	The original invoice is voided via a credit note; a new invoice is issued with the corrected totals.
Operator-initiated POST /v1/invoices/{id}/credit-notes	Ad-hoc credit. Requires AAL2 in production.

Shape

{
  "id": "cn_…",
  "number": "CN-2026-000045",
  "invoice_id": "inv_…",
  "customer_id": "cus_…",
  "currency": "USD",
  "reason": "duplicate",
  "status": "issued",
  "issued_at": "2026-05-07T10:14:00Z",
  "lines": [
    { "description": "Refund: Pro – May 2026 (partial)", "amount": "-25.00" }
  ],
  "subtotal": "-25.00",
  "tax": "-1.80",
  "total": "-26.80",
  "outcome": {
    "kind": "refund",
    "refund_id": "ref_…",
    "amount_refunded": "26.80"
  }
}

outcome.kind is one of:

• refund — cash was returned to the original payment method.
• credit_balance — the amount was added to the customer’s wallet.
• applied_to_invoice — the amount reduced amount_due on the original invoice.

Issuing a credit note

POST /v1/invoices/{id}/credit-notes
Idempotency-Key: <uuid>

{
  "reason": "service_outage",
  "lines": [
    { "description": "Goodwill credit – outage 2026-05-04", "amount": "-50.00" }
  ],
  "outcome": "credit_balance"
}

Allowed reason values: duplicate, fraudulent, order_change, product_unsatisfactory, service_outage, other.

Required when outcome: refund and the invoice is paid: nothing — Paylera picks the original payment method. To refund to a different method (rare, sometimes needed for chargebacks), include payment_method_id.

Tax handling

Credit notes recompute tax against the credited amount, in the same jurisdiction the original invoice was taxed. Some tax engines require a specific reason code on credit notes (for VAT / GST audit trails); the engine sets it automatically based on reason.

Constraints

• The total of all credit notes against an invoice cannot exceed the invoice total.
• A void credit note (outcome: applied_to_invoice) on a partially-paid invoice cannot reduce amount_due below amount_paid.
• Once a credit note is issued, it cannot be edited or deleted. To reverse a mistakenly-issued credit note, issue a positive credit note (a “debit note”) with reason: other.

Webhook events

Event	When
credit_note.created	A credit note was issued.
credit_note.refund_succeeded	Cash was returned to the customer (when outcome: refund).
credit_note.refund_failed	The provider rejected the refund.

For the integration recipe, see Refund a payment.