Credit Notes

Overview

Credit notes formalize adjustments to invoices. When a customer is overcharged, cancels an order, or receives unsatisfactory service, a credit note records the correction and determines whether the amount is applied as account credit, issued as a refund, or used to offset another charge.

How credit notes work

Invoice dispute or adjustment needed
        │
        ▼
  Create credit note (draft)
        │
        ▼
  Add line items (by fee)
        │
        ▼
  Review & finalize ──► credit_note.created webhook
        │
        ├──► Credit ──► Applied to customer balance
        │                (credit_status: available → consumed)
        │
        ├──► Refund ──► Returned to payment method
        │                (refund_status: pending → succeeded/failed)
        │
        └──► Offset ──► Applied against another charge

Credit note properties

Field	Type	Description
id	uuid	Unique credit note identifier
number	string	Credit note number (max 50 chars)
invoice_id	uuid	Associated invoice
customer_id	uuid	Associated customer
credit_note_type	string	credit, refund, or offset
status	string	draft or finalized
credit_status	string?	available, consumed, or voided
refund_status	string?	pending, succeeded, or failed
reason	string	Reason for the credit note (see below)
description	string?	Optional description
credit_amount_cents	string	Amount credited to customer balance
refund_amount_cents	string	Amount refunded to payment method
balance_amount_cents	string	Remaining balance
total_amount_cents	string	Total credit note amount
taxes_amount_cents	string	Tax portion of the amount
currency	string	3-letter ISO currency code
issued_at	datetime?	When the credit note was finalized
voided_at	datetime?	When the credit note was voided
created_at	datetime	Creation timestamp
updated_at	datetime	Last update timestamp

Credit note reasons

Value	Description
duplicated_charge	Customer was charged twice for the same item
product_unsatisfactory	Product or service did not meet expectations
order_change	Order was modified after billing
order_cancellation	Order was cancelled
fraudulent_charge	Charge was identified as fraudulent
other	Other reason (use description for details)

Credit note types

Type	Behavior
credit	Amount is added to the customer’s account balance for future use
refund	Amount is returned to the customer’s original payment method
offset	Amount is applied against another charge or invoice

Create a credit note

Credit notes are created in draft status, allowing you to review before finalizing.

curl -X POST /v1/credit_notes/ \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "CN-2026-0001",
    "invoice_id": "invoice-uuid",
    "customer_id": "customer-uuid",
    "credit_note_type": "credit",
    "reason": "order_cancellation",
    "description": "Subscription cancelled mid-cycle",
    "credit_amount_cents": 5000,
    "total_amount_cents": 5000,
    "taxes_amount_cents": 0,
    "currency": "USD",
    "items": [
      {"fee_id": "fee-uuid-1", "amount_cents": 3000},
      {"fee_id": "fee-uuid-2", "amount_cents": 2000}
    ]
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "CN-2026-0001",
  "invoice_id": "invoice-uuid",
  "customer_id": "customer-uuid",
  "credit_note_type": "credit",
  "status": "draft",
  "credit_status": null,
  "refund_status": null,
  "reason": "order_cancellation",
  "description": "Subscription cancelled mid-cycle",
  "credit_amount_cents": "5000",
  "refund_amount_cents": "0",
  "balance_amount_cents": "5000",
  "total_amount_cents": "5000",
  "taxes_amount_cents": "0",
  "currency": "USD",
  "issued_at": null,
  "voided_at": null,
  "created_at": "2026-03-08T10:00:00Z",
  "updated_at": "2026-03-08T10:00:00Z"
}

The number must be unique across all credit notes. Line items reference specific fees from the original invoice.

Update a draft credit note

Only credit notes in draft status can be updated.

curl -X PUT /v1/credit_notes/{credit_note_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "product_unsatisfactory",
    "description": "Updated: service outage during billing period",
    "credit_amount_cents": 7500,
    "total_amount_cents": 7500
  }'

All update fields are optional — only the fields you include are modified. Attempting to update a finalized credit note returns a 400 error.

Finalize a credit note

Finalizing locks the credit note and triggers the credit or refund. Only draft credit notes can be finalized.

curl -X POST /v1/credit_notes/{credit_note_id}/finalize \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "number": "CN-2026-0001",
  "status": "finalized",
  "credit_status": "available",
  "issued_at": "2026-03-08T12:00:00Z",
  "...": "..."
}

After finalization:

• Credit type — the credit_status is set to available and the amount is added to the customer’s balance
• Refund type — the refund_status is set to pending and the refund is initiated through the payment provider
• The issued_at timestamp is recorded
• The credit note can no longer be edited

Void a credit note

Voiding reverses a finalized credit note. Only finalized credit notes can be voided.

curl -X POST /v1/credit_notes/{credit_note_id}/void \
  -H "Authorization: Bearer $API_KEY"

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "finalized",
  "credit_status": "voided",
  "voided_at": "2026-03-08T15:00:00Z",
  "...": "..."
}

Voiding a credit note sets voided_at and updates the credit_status to voided. Any credit that was applied to the customer’s balance is reversed.

Download PDF

Generate and download a PDF for a finalized credit note. Draft credit notes cannot generate PDFs.

curl -X POST /v1/credit_notes/{credit_note_id}/download_pdf \
  -H "Authorization: Bearer $API_KEY"

Send email notification

Send the credit note to the customer via email. The credit note must be finalized first.

curl -X POST /v1/credit_notes/{credit_note_id}/send_email \
  -H "Authorization: Bearer $API_KEY"

List and filter credit notes

# List all credit notes
curl /v1/credit_notes/ \
  -H "Authorization: Bearer $API_KEY"

# Filter by customer
curl "/v1/credit_notes/?customer_id=customer-uuid" \
  -H "Authorization: Bearer $API_KEY"

# Filter by invoice
curl "/v1/credit_notes/?invoice_id=invoice-uuid" \
  -H "Authorization: Bearer $API_KEY"

# Filter by status
curl "/v1/credit_notes/?status=finalized" \
  -H "Authorization: Bearer $API_KEY"

Supports pagination with skip and limit query parameters (default: 100 items, max: 1000). Use order_by to sort results.

Credit note lifecycle

  draft ──────► finalized ──────► voided
    │               │
    │               ├─ credit_status: available → consumed
    │               │                           → voided
    │               │
    │               └─ refund_status: pending → succeeded
    │                                        → failed
    │
    └─ Can be updated or deleted

• Draft — editable, not yet applied. Can be updated or deleted.
• Finalized — locked and applied. Credit is available or refund is pending. Can be voided.
• Voided — reversed. Credit is reclaimed from the customer’s balance.

Entity relationships

• Invoice — every credit note references exactly one invoice via invoice_id
• Customer — tied to a customer via customer_id
• Fees — line items reference specific fees from the original invoice via fee_id
• Wallet — credit-type notes add balance to the customer’s wallet
• Payments — refund-type notes initiate a return through the payment provider

API endpoints

Method	Path	Description
POST	/v1/credit_notes/	Create a credit note
GET	/v1/credit_notes/	List credit notes
GET	/v1/credit_notes/{credit_note_id}	Get a credit note
PUT	/v1/credit_notes/{credit_note_id}	Update a credit note (draft only)
POST	/v1/credit_notes/{credit_note_id}/finalize	Finalize a credit note
POST	/v1/credit_notes/{credit_note_id}/void	Void a credit note
POST	/v1/credit_notes/{credit_note_id}/download_pdf	Download credit note PDF
POST	/v1/credit_notes/{credit_note_id}/send_email	Send credit note email