Error

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"
  }
}

Credit notes

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.

POST

credit_notes

Error

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

Authorization

string

header

required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

required

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.

Maximum string length: 255

Body

application/json

Provide either lines or amount (not both). Settlement fields amount_refunded and out_of_band_amount must sum to the credit total.

invoice

string

required

The paid invoice to credit (inv_…). Must be in paid status.

lines

object[]

Explicit credit lines. Mutually exclusive with amount.

Show child attributes

amount

integer | null

Shorthand for a single custom-line credit of this amount in minor units. Mutually exclusive with lines.

amount_refunded

integer

default:0

Portion of the credit already returned via an existing refund, in minor units. Requires refund.

out_of_band_amount

integer

default:0

Portion of the credit settled outside the payment platform (for example, a check), in minor units.

refund

string | null

An already-created refund to link (rf_…). Required when amount_refunded is non-zero.

reason

enum<string> | null

Why the credit is being issued. Omit if no reason applies.

Available options:

duplicate,

fraudulent,

order_change,

product_unsatisfactory,

adjustment

memo

string | null

Free-text note printed on the credit note PDF.

effective_at

integer | null

Unix epoch seconds to backdate the credit note. Defaults to the time of the request.

metadata

object

Show child attributes

Response

The created credit note.

string

required

Credit note id (cn_…).

object

enum<string>

required

Available options:

credit_note

number

string

required

The gapless per-merchant number assigned at creation (for example CN-000001).

invoice

string

required

The invoice this credit note offsets (inv_…).

customer

string

required

The customer the invoice was issued to (cus_…).

currency

string

required

Three-letter ISO currency code.

status

enum<string>

required

issued is the normal state after creation; void means the credit note has been reversed.

Available options:

issued,

void

type

enum<string>

required

Always post_payment in v1.

Available options:

post_payment

reason

enum<string> | null

required

The reason given at creation, or null if none was provided.

Available options:

duplicate,

fraudulent,

order_change,

product_unsatisfactory,

adjustment

subtotal

integer

required

Sum of line amounts before tax, in minor units.

tax

integer

required

Total tax credited, in minor units.

total

integer

required

Total credit amount (subtotal + tax), in minor units.

amount_refunded

integer

required

Portion returned via the linked refund, in minor units.

out_of_band_amount

integer

required

Portion settled outside the platform, in minor units.

refund

string | null

required

The linked refund (rf_…), or null when settlement was out-of-band only.

lines

object[]

required

Show child attributes

memo

string | null

required

Free-text note printed on the PDF, or null if none was provided.

livemode

boolean

required

created

integer

required

Unix epoch seconds.

effective_at

integer

required

Unix epoch seconds the credit is dated to.

voided_at

integer | null

required

Unix epoch seconds when the note was voided, or null while still issued.

metadata

object

required

Show child attributes

hosted_url

string | null

Buyer-facing permalink for the hosted credit note view, when the hosted surface is enabled. Omitted otherwise.

Start here

Checkout

Commerce

Checkout endpoints

Payment link endpoints

Catalog endpoints

Payments

Terminal locations

Terminal management

Terminal testing

Terminal payments

Invoices

Subscriptions

Setup intents

Credit notes

Webhook endpoints

Customer endpoints

API key endpoints

Payment method endpoints

Create a credit note

Authorizations

Headers

Body

Response