A valid request URL is required to generate request examples{
"id": "<string>",
"object": "credit_note",
"number": "<string>",
"invoice": "<string>",
"customer": "<string>",
"currency": "<string>",
"status": "issued",
"type": "post_payment",
"reason": "duplicate",
"subtotal": 123,
"tax": 123,
"total": 123,
"amount_refunded": 123,
"out_of_band_amount": 123,
"refund": "<string>",
"lines": [
{
"id": "<string>",
"object": "credit_note_line_item",
"type": "invoice_line_item",
"invoice_line_item": "<string>",
"description": "<string>",
"quantity": 123,
"unit_amount": 123,
"amount": 123,
"tax": 123,
"livemode": true
}
],
"memo": "<string>",
"livemode": true,
"created": 123,
"effective_at": 123,
"voided_at": 123,
"metadata": {},
"hosted_url": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "provide either lines or a single amount, not both"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "invoice not found"
}
}{
"error": {
"code": "CREDIT_NOTE_REFUND_ALREADY_CREDITED",
"message": "a credit note already credits this refund"
}
}{
"error": {
"code": "INVALID_CREDIT_NOTE_STATE",
"message": "invalid credit note state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "PDF_RENDER_FAILED",
"message": "failed to render credit note PDF"
}
}Create a credit note
Issues a credit note against a paid invoice. The invoice must be in
paid status; creating against a draft, open, void, or uncollectible
invoice returns 422.
Supply either lines (one or more explicit credit lines) or amount
(a shorthand that creates a single custom-line credit for the whole
amount). Supplying both returns 400.
Settlement must be accounted for: amount_refunded (linked to an
already-created refund rf_… via refund) plus out_of_band_amount
must equal the credit total. The sum of all credit notes against an
invoice cannot exceed the invoice total; exceeding it returns 422
with CREDIT_NOTE_OVER_CREDIT.
Send an Idempotency-Key header so a retried request replays the first
credit note rather than issuing a duplicate.
A valid request URL is required to generate request examples{
"id": "<string>",
"object": "credit_note",
"number": "<string>",
"invoice": "<string>",
"customer": "<string>",
"currency": "<string>",
"status": "issued",
"type": "post_payment",
"reason": "duplicate",
"subtotal": 123,
"tax": 123,
"total": 123,
"amount_refunded": 123,
"out_of_band_amount": 123,
"refund": "<string>",
"lines": [
{
"id": "<string>",
"object": "credit_note_line_item",
"type": "invoice_line_item",
"invoice_line_item": "<string>",
"description": "<string>",
"quantity": 123,
"unit_amount": 123,
"amount": 123,
"tax": 123,
"livemode": true
}
],
"memo": "<string>",
"livemode": true,
"created": 123,
"effective_at": 123,
"voided_at": 123,
"metadata": {},
"hosted_url": "<string>"
}{
"error": {
"code": "INVALID_DATA",
"message": "provide either lines or a single amount, not both"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "INVOICE_NOT_FOUND",
"message": "invoice not found"
}
}{
"error": {
"code": "CREDIT_NOTE_REFUND_ALREADY_CREDITED",
"message": "a credit note already credits this refund"
}
}{
"error": {
"code": "INVALID_CREDIT_NOTE_STATE",
"message": "invalid credit note state for this operation"
}
}{
"error": {
"code": "<string>",
"message": "<string>"
}
}{
"error": {
"code": "PDF_RENDER_FAILED",
"message": "failed to render credit note PDF"
}
}Authorizations
A merchant secret key (sk_…) sent as Authorization: Bearer <key>.
Headers
Merchant ID when an authorized Platform acts for a connected Merchant. Omit when authenticating directly as that Merchant.
^mer_[0-9A-Za-z]{14}$Required. A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.
255Body
Provide either lines or amount (not both). Settlement fields
amount_refunded and out_of_band_amount must sum to the credit total.
The paid invoice to credit (inv_…). Must be in paid status.
Explicit credit lines. Mutually exclusive with amount.
Show child attributes
Show child attributes
Shorthand for a single custom-line credit of this amount in minor units. Mutually exclusive with lines.
Portion of the credit already returned via an existing refund, in minor units. Requires refund.
Portion of the credit settled outside the payment platform (for example, a check), in minor units.
An already-created refund to link (rf_…). Required when amount_refunded is non-zero.
Why the credit is being issued. Omit if no reason applies.
duplicate, fraudulent, order_change, product_unsatisfactory, adjustment Free-text note printed on the credit note PDF.
Unix epoch seconds to backdate the credit note. Defaults to the time of the request.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Response
The created credit note.
Credit note id (cn_…).
credit_note The gapless per-merchant number assigned at creation (for example CN-000001).
The invoice this credit note offsets (inv_…).
The customer the invoice was issued to (cus_…).
Three-letter ISO currency code.
issued is the normal state after creation; void means the credit note has been reversed.
issued, void Always post_payment.
post_payment The reason given at creation, or null if none was provided.
duplicate, fraudulent, order_change, product_unsatisfactory, adjustment Sum of line amounts before tax, in minor units.
Total tax credited, in minor units.
Total credit amount (subtotal + tax), in minor units.
Portion returned via the linked refund, in minor units.
Portion settled outside the platform, in minor units.
The linked refund (rf_…), or null when settlement was out-of-band only.
The credit lines on this note.
Show child attributes
Show child attributes
Free-text note printed on the PDF, or null if none was provided.
Unix epoch seconds.
Unix epoch seconds the credit is dated to.
Unix epoch seconds when the note was voided, or null while still issued.
Custom key-value pairs for your use.
Show child attributes
Show child attributes
Buyer-facing permalink for the hosted credit note view, when the hosted surface is enabled. Omitted otherwise.