The Credit Note object

Attributes

id string Unique identifier for the object.
currency enum Three-letter ISO currency code, in lowercase. Must be a supported currency.
invoice string Expandable ID of the invoice.
lines object Line items that make up the credit note
memo nullable string Customer-facing text that appears on the credit note PDF.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
reason nullable enum Reason for issuing this credit note, one of duplicate, fraudulent, order_change, or product_unsatisfactory Possible enum values duplicate Credit issued for a duplicate payment or charge fraudulent Credit note issued for fraudulent activity order_change Credit note issued for order change product_unsatisfactory Credit note issued for unsatisfactory product
status enum Status of this credit note, one of issued or void. Learn more about voiding credit notes. Possible enum values issued The credit note has been issued. void The credit note has been voided.
subtotal integer The integer amount in the smallest currency unit representing the amount of the credit note, excluding exclusive tax and invoice level discounts.
total integer The integer amount in the smallest currency unit representing the total amount of the credit note, including tax and all discount.

More attributes

object string, value is "credit_note"
amount integer
amount _ shipping integer
created timestamp
customer string Expandable
customer _ account nullable string
customer _ balance _ transaction nullable string Expandable
discount _ amount integer Deprecated
discount _ amounts array of objects
effective _ at nullable timestamp
livemode boolean
number string
out _ of _ band _ amount nullable integer
pdf string
post _ payment _ amount integer
pre _ payment _ amount integer
pretax _ credit _ amounts array of objects
refunds array of objects
shipping _ cost nullable object
subtotal _ excluding _ tax nullable integer
total _ excluding _ tax nullable integer
total _ taxes nullable array of objects
type enum
voided _ at nullable timestamp

The Credit Note Line Item object

Attributes

id string Unique identifier for the object.
object string, value is "credit_note_line_item" String representing the object’s type. Objects of the same type share the same value.
amount integer The integer amount in the smallest currency unit representing the gross amount being credited for this line item, excluding (exclusive) tax and discounts.
description nullable string Description of the item being credited.
discount _ amount integer Deprecated The integer amount in the smallest currency unit representing the discount being credited for this line item.
discount _ amounts array of objects The amount of discount calculated per discount for this line item
invoice _ line _ item nullable string ID of the invoice line item being credited
livemode boolean If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.
metadata nullable map Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
pretax _ credit _ amounts array of objects The pretax credit amounts (ex: discount, credit grants, etc) for this line item.
quantity nullable integer The number of units of product being credited.
tax _ rates array of objects The tax rates which apply to the line item.
taxes nullable array of objects The tax information of the line item.
type enum The type of the credit note line item, one of invoice_line_item or custom_line_item. When the type is invoice_line_item there is an additional invoice_line_item property on the resource the value of which is the id of the credited line item on the invoice. Possible enum values custom_line_item invoice_line_item
unit _ amount nullable integer The cost of each unit of product being credited.
unit _ amount _ decimal nullable decimal string Same as unit_amount, but contains a decimal value with at most 12 decimal places.

The Credit Note Line Item object

{ "id": "cnli_1NPtOx2eZvKYlo2CBH1NpUsU", "object": "credit_note_line_item", "amount": 749, "description": "My First Invoice Item (created for API docs)", "discount_amount": 0, "discount_amounts": [], "invoice_line_item": "il_1NPtOx2eZvKYlo2CAUuq0WVl", "livemode": false, "quantity": 1, "taxes": [], "tax_rates": [], "type": "invoice_line_item", "unit_amount": null, "unit_amount_decimal": null}

Create a credit note

POST / v1 / credit_notes

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.

Parameters

invoice string Required ID of the invoice.
lines array of objects Required conditionally Line items that make up the credit note. One of amount, lines, or shipping_cost must be provided.
memo string The credit note’s memo appears on the credit note PDF.
metadata map Set of key-value pairs 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.
reason enum Reason for issuing this credit note, one of duplicate, fraudulent, order_change, or product_unsatisfactory Possible enum values duplicate Credit issued for a duplicate payment or charge fraudulent Credit note issued for fraudulent activity order_change Credit note issued for order change product_unsatisfactory Credit note issued for unsatisfactory product

More parameters

amount integer Required conditionally
credit _ amount integer
effective _ at timestamp
email _ type enum
out _ of _ band _ amount integer
refund _ amount integer
refunds array of objects
shipping _ cost object Required conditionally

Returns

Returns a credit note object if the call succeeded.

Response