Preview a credit note

Error

A valid request URL is required to generate request examples

{
  "object": "credit_note_preview",
  "currency": "<string>",
  "type": "post_payment",
  "subtotal": 123,
  "tax": 123,
  "total": 123,
  "amount_refunded": 123,
  "out_of_band_amount": 123,
  "invoice_total": 123,
  "already_credited": 123,
  "creditable_remaining": 123,
  "would_exceed": true
}

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

POST

credit_notes

preview

Error

A valid request URL is required to generate request examples

{
  "object": "credit_note_preview",
  "currency": "<string>",
  "type": "post_payment",
  "subtotal": 123,
  "tax": 123,
  "total": 123,
  "amount_refunded": 123,
  "out_of_band_amount": 123,
  "invoice_total": 123,
  "already_credited": 123,
  "creditable_remaining": 123,
  "would_exceed": true
}

{
  "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": "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

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 computed credit note preview.

A computed credit note preview — no id, number, or lines, because nothing is persisted.

object

enum<string>

required

Available options:

credit_note_preview

currency

string

required

Three-letter ISO currency code.

type

enum<string>

required

Available options:

post_payment

subtotal

integer

required

Sum of line amounts before tax, in minor units.

tax

integer

required

Tax credited, in minor units.

total

integer

required

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

amount_refunded

integer

required

Portion to be settled via the linked refund, in minor units.

out_of_band_amount

integer

required

Portion settled outside the platform, in minor units.

invoice_total

integer

required

The invoice's original total, in minor units.

already_credited

integer

required

Amount already credited by prior credit notes, in minor units.

creditable_remaining

integer

required

How much more can be credited before hitting the cap, in minor units.

would_exceed

boolean

required

True when this credit would exceed the invoice's creditable remaining. A subsequent create call will be rejected with CREDIT_NOTE_OVER_CREDIT.

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

Preview a credit note

Authorizations

Headers

Body

Response