Sample - Stripe API
POST/v1/credit_notes

Create a credit note

Issue a credit note to adjust the amount of a finalized invoice. A credit note will first reduce the invoice’s amount_remaining (and amount_due), but not below zero. This amount is indicated by the credit note’s pre_payment_amount. The excess amount is indicated by post_payment_amount, and it can result in any combination of the following:

  • Refunds: create a new refund (using refund_amount) or link existing refunds (using refunds).
  • Customer balance credit: credit the customer’s balance (using credit_amount) which will be automatically applied to their next invoice when it’s finalized.
  • Outside of Stripe credit: record the amount that is or will be credited outside of Stripe (using out_of_band_amount).

The sum of refunds, customer balance credits, and outside of Stripe credits must equal the post_payment_amount.

You may issue multiple credit notes for an invoice. Each credit note may increment the invoice’s pre_payment_credit_notes_amount, post_payment_credit_notes_amount, or both, depending on the invoice’s amount_remaining at the time of credit note creation.

For invoices that also have refunds created through the Refund API, the credit note API subtracts those refund amounts from the maximum creditable amount. This prevents the combined credit notes and refunds from exceeding the invoice amount. If you use both, ensure the combined total does not exceed the invoice’s paid amount.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

14 body fields
amountintegeroptional
The integer amount in cents (or local equivalent) representing the total amount of the credit note. One of `amount`, `lines`, or `shipping_cost` must be provided.
credit_amountintegeroptional
The integer amount in cents (or local equivalent) representing the amount to credit the customer's balance, which will be automatically applied to their next invoice.
effective_atintegeroptional
The date when this credit note is in effect. Same as `created` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the credit note PDF.
email_typestringoptional
Type of email to send to the customer, one of `credit_note` or `none` and the default is `credit_note`.
Allowed:credit_notenone
expandarray<string>optional
Specifies which fields in the response should be expanded.
invoicestringrequired
ID of the invoice.
linesarray<CreditNoteLineItemParams>optional
Line items that make up the credit note. One of `amount`, `lines`, or `shipping_cost` must be provided.
memostringoptional
The credit note's memo appears on the credit note PDF.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
out_of_band_amountintegeroptional
The integer amount in cents (or local equivalent) representing the amount that is credited outside of Stripe.
reasonstringoptional
Reason for issuing this credit note, one of `duplicate`, `fraudulent`, `order_change`, or `product_unsatisfactory`
Allowed:duplicatefraudulentorder_changeproduct_unsatisfactory
refund_amountintegeroptional
The integer amount in cents (or local equivalent) representing the amount to refund. If set, a refund will be created for the charge associated with the invoice.
refundsarray<CreditNoteRefundParams>optional
Refunds to link to this credit note.
shipping_costobjectoptional
When shipping_cost contains the shipping_rate from the invoice, the shipping_cost is included in the credit note. One of `amount`, `lines`, or `shipping_cost` must be provided.

2 status codes
200Successful response.
amountintegerrequired
The integer amount in cents (or local equivalent) representing the total amount of the credit note, including tax.
amount_shippingintegerrequired
This is the sum of all the shipping amounts.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
currencystringrequired
Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
customerstringrequired
ID of the customer.
customer_accountstringoptional
ID of the account representing the customer.
customer_balance_transactionstringoptional
Customer balance transaction related to this credit note.
discount_amountintegerrequired
The integer amount in cents (or local equivalent) representing the total amount of discount that was credited.
discount_amountsarray<DiscountsResourceDiscountAmount>required
The aggregate amounts calculated per discount for all line items.
effective_atintegeroptional
The date when this credit note is in effect. Same as `created` unless overwritten. When defined, this value replaces the system-generated 'Date of issue' printed on the credit note PDF.
idstringrequired
Unique identifier for the object.
invoicestringrequired
ID of the invoice.
linesobjectrequired
Line items that make up the credit note
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
memostringoptional
Customer-facing text that appears on the credit note PDF.
metadataobjectoptional
Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
numberstringrequired
A unique number that identifies this particular credit note and appears on the PDF of the credit note and its associated invoice.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:credit_note
out_of_band_amountintegeroptional
Amount that was credited outside of Stripe.
pdfstringrequired
The link to download the PDF of the credit note.
post_payment_amountintegerrequired
The amount of the credit note that was refunded to the customer, credited to the customer's balance, credited outside of Stripe, or any combination thereof.
pre_payment_amountintegerrequired
The amount of the credit note by which the invoice's `amount_remaining` and `amount_due` were reduced.
pretax_credit_amountsarray<CreditNotesPretaxCreditAmount>required
The pretax credit amounts (ex: discount, credit grants, etc) for all line items.
reasonstringoptional
Reason for issuing this credit note, one of `duplicate`, `fraudulent`, `order_change`, or `product_unsatisfactory`
Allowed:duplicatefraudulentorder_changeproduct_unsatisfactory
refundsarray<CreditNoteRefund>required
Refunds related to this credit note.
shipping_costobjectoptional
The details of the cost of shipping, including the ShippingRate applied to the invoice.
statusstringrequired
Status of this credit note, one of `issued` or `void`. Learn more about [voiding credit notes](https://docs.stripe.com/billing/invoices/credit-notes#voiding).
Allowed:issuedvoid
subtotalintegerrequired
The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding exclusive tax and invoice level discounts.
subtotal_excluding_taxintegeroptional
The integer amount in cents (or local equivalent) representing the amount of the credit note, excluding all tax and invoice level discounts.
totalintegerrequired
The integer amount in cents (or local equivalent) representing the total amount of the credit note, including tax and all discount.
total_excluding_taxintegeroptional
The integer amount in cents (or local equivalent) representing the total amount of the credit note, excluding tax, but including discounts.
total_taxesarray<BillingBillResourceInvoicingTaxesTax>optional
The aggregate tax information for all line items.
typestringrequired
Type of this credit note, one of `pre_payment` or `post_payment`. A `pre_payment` credit note means it was issued when the invoice was open. A `post_payment` credit note means it was issued when the invoice was paid.
Allowed:mixedpost_paymentpre_payment
voided_atintegeroptional
The time that the credit note was voided.
defaultError response.
errorobjectrequired

Error handling

Any other status is an error: Error response.