Create a credit note
Issue a credit note to adjust the amount of a finalized invoice. For a status=open
invoice, a credit note reduces its amount_due
. For a status=paid
invoice, a credit note does not affect its amount_due
. Instead, it can result in any combination of the following:
- Refund: create a new refund (using
refund_amount
) or link an existing refund (usingrefund
). - 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
).
For post-payment credit notes the sum of the refund, credit and outside of Stripe amounts must equal the credit note total.
You may issue multiple credit notes for an invoice. Each credit note will increment the invoice’s pre_payment_credit_notes_amount
or post_payment_credit_notes_amount
depending on its status
at the time of credit note creation.
Parameters
- invoicestringRequired
ID of the invoice.
- linesarray of objects
Line items that make up the credit note.
- memostring
The credit note’s memo appears on the credit note PDF.
- metadataobject
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
. - reasonenum
Reason for issuing this credit note, one of
duplicate
,fraudulent
,order_change
, orproduct_unsatisfactory
Possible enum valuesduplicate
fraudulent
order_change
product_unsatisfactory
More parameters
- amountinteger
- credit_
amountinteger - effective_
attimestamp - out_
of_ band_ amountinteger - refundstring
- refund_
amountinteger - shipping_
costobject
Returns
Returns a credit note object if the call succeeded.
{
"id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
"object": "credit_note",
"amount": 1099,
"amount_shipping": 0,
"created": 1681750958,
"currency": "usd",
"customer": "cus_NjLgPhUokHubJC",
"customer_balance_transaction": null,
"discount_amount": 0,
"discount_amounts": [],
"invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
"lines": {
"object": "list",
"data": [
{
"id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
"object": "credit_note_line_item",
"amount": 1099,
"amount_excluding_tax": 1099,
"description": "T-shirt",
"discount_amount": 0,
"discount_amounts": [],
"invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
"livemode": false,
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
"type": "invoice_line_item",
"unit_amount": 1099,
"unit_amount_decimal": "1099",
"unit_amount_excluding_tax": "1099"
}
],
"has_more": false,
"url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
},
"livemode": false,
"memo": null,
"metadata": {},
"number": "C9E0C52C-0036-CN-01",
"out_of_band_amount": null,
"pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
"reason": null,
"refund": null,
"shipping_cost": null,
"status": "issued",
"subtotal": 1099,
"subtotal_excluding_tax": 1099,
"tax_amounts": [],
"total": 1099,
"total_excluding_tax": 1099,
"type": "pre_payment",
"voided_at": null
}
Update a credit note
Updates an existing credit note.
Parameters
- memostring
Credit note memo.
- metadataobject
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
.
Returns
Returns the updated credit note object if the call succeeded.
{
"id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
"object": "credit_note",
"amount": 1099,
"amount_shipping": 0,
"created": 1681750958,
"currency": "usd",
"customer": "cus_NjLgPhUokHubJC",
"customer_balance_transaction": null,
"discount_amount": 0,
"discount_amounts": [],
"invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
"lines": {
"object": "list",
"data": [
{
"id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
"object": "credit_note_line_item",
"amount": 1099,
"amount_excluding_tax": 1099,
"description": "T-shirt",
"discount_amount": 0,
"discount_amounts": [],
"invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
"livemode": false,
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
"type": "invoice_line_item",
"unit_amount": 1099,
"unit_amount_decimal": "1099",
"unit_amount_excluding_tax": "1099"
}
],
"has_more": false,
"url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
},
"livemode": false,
"memo": null,
"metadata": {
"order_id": "6735"
},
"number": "C9E0C52C-0036-CN-01",
"out_of_band_amount": null,
"pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
"reason": null,
"refund": null,
"shipping_cost": null,
"status": "issued",
"subtotal": 1099,
"subtotal_excluding_tax": 1099,
"tax_amounts": [],
"total": 1099,
"total_excluding_tax": 1099,
"type": "pre_payment",
"voided_at": null
}
Retrieve a credit note's line items
When retrieving a credit note, you’ll get a lines property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
Parameters
No parameters.
More parameters
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
Returns a list of line_item objects.
{
"object": "list",
"url": "/v1/credit_notes/cn_1NPtPy2eZvKYlo2CPaEMGMY8/lines",
"has_more": false,
"data": [
{
"object": "list",
"url": "/v1/credit_notes/cn_1Nn7fB2eZvKYlo2CuJ0wZBlA/lines",
"has_more": false,
"data": [
{
"id": "cnli_1Nn7fB2eZvKYlo2COYgPG88j",
"object": "credit_note_line_item",
"amount": 799,
"amount_excluding_tax": 799,
"description": "My First Invoice Item (created for API docs)",
"discount_amount": 0,
"discount_amounts": [],
"invoice_line_item": "il_1Nn7fB2eZvKYlo2C3GKZP9wi",
"livemode": false,
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
"type": "invoice_line_item",
"unit_amount": null,
"unit_amount_decimal": null,
"unit_amount_excluding_tax": "799"
}
]
}
{...}
{...}
],
}
Retrieve a credit note preview's line items
When retrieving a credit note preview, you’ll get a lines property containing the first handful of those items. This URL you can retrieve the full (paginated) list of line items.
Parameters
- invoicestringRequired
ID of the invoice.
- linesarray of objects
Line items that make up the credit note.
- memostring
The credit note’s memo appears on the credit note PDF.
- metadataobject
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
. - reasonenum
Reason for issuing this credit note, one of
duplicate
,fraudulent
,order_change
, orproduct_unsatisfactory
Possible enum valuesduplicate
fraudulent
order_change
product_unsatisfactory
More parameters
- amountinteger
- credit_
amountinteger - effective_
attimestamp - ending_
beforestring - limitinteger
- out_
of_ band_ amountinteger - refundstring
- refund_
amountinteger - shipping_
costobject - starting_
afterstring
Returns
Returns a list of line_item objects.
{
"id": "cn_1Nn7fB2eZvKYlo2CuJ0wZBlA",
"object": "credit_note",
"amount": 1451,
"amount_shipping": 0,
"created": 1693952641,
"currency": "usd",
"customer": "cus_9s6XKzkNRiz8i3",
"customer_balance_transaction": null,
"discount_amount": 0,
"discount_amounts": [],
"effective_at": null,
"invoice": "in_1Nn7fB2eZvKYlo2C7meA67Xp",
"lines": {
"object": "list",
"data": [
{
"id": "cnli_1Nn7fB2eZvKYlo2Cp8nLMci9",
"object": "credit_note_line_item",
"amount": 951,
"amount_excluding_tax": 951,
"description": "My First Invoice Item (created for API docs)",
"discount_amount": 0,
"discount_amounts": [],
"invoice_line_item": "il_1Nn7fB2eZvKYlo2ChKG2H1tv",
"livemode": false,
"quantity": 1,
"tax_amounts": [
{
"amount": 152,
"inclusive": false,
"tax_rate": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD",
"taxability_reason": null,
"taxable_amount": 799
}
],
"tax_rates": [
{
"id": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD",
"object": "tax_rate",
"active": true,
"country": "DE",
"created": 1693952641,
"description": "VAT Germany",
"display_name": "VAT",
"effective_percentage": null,
"inclusive": false,
"jurisdiction": "DE",
"livemode": false,
"metadata": {},
"percentage": 19,
"state": null,
"tax_type": "vat"
}
],
"type": "invoice_line_item",
"unit_amount": null,
"unit_amount_decimal": null,
"unit_amount_excluding_tax": "951"
},
{
"id": "cnli_1Nn7fB2eZvKYlo2C7OxQLHdz",
"object": "credit_note_line_item",
"amount": 500,
"amount_excluding_tax": 500,
"description": "Service credit",
"discount_amount": 0,
"discount_amounts": [],
"livemode": false,
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
"type": "custom_line_item",
"unit_amount": 500,
"unit_amount_decimal": "500",
"unit_amount_excluding_tax": "500"
}
],
"has_more": false,
"url": "/v1/credit_notes/cn_1Nn7fB2eZvKYlo2CuJ0wZBlA/lines"
},
"livemode": false,
"memo": null,
"metadata": {},
"number": "ABCD-1234-CN-01",
"out_of_band_amount": null,
"pdf": "https://pay.stripe.com/credit_notes/acct_1032D82eZvKYlo2C/cnst_123456789/pdf?s=ap",
"reason": null,
"refund": null,
"shipping_cost": null,
"status": "issued",
"subtotal": 1451,
"subtotal_excluding_tax": 1451,
"tax_amounts": [
{
"amount": 152,
"inclusive": false,
"tax_rate": "txr_1Nn7fB2eZvKYlo2CcbF7zzmD",
"taxability_reason": null,
"taxable_amount": 799
}
],
"total": 1451,
"total_excluding_tax": null,
"type": "pre_payment",
"voided_at": null
}
Retrieve a credit note
Retrieves the credit note object with the given identifier.
Parameters
No parameters.
Returns
Returns a credit note object if a valid identifier was provided.
{
"id": "cn_1MxvRqLkdIwHu7ixY0xbUcxk",
"object": "credit_note",
"amount": 1099,
"amount_shipping": 0,
"created": 1681750958,
"currency": "usd",
"customer": "cus_NjLgPhUokHubJC",
"customer_balance_transaction": null,
"discount_amount": 0,
"discount_amounts": [],
"invoice": "in_1MxvRkLkdIwHu7ixABNtI99m",
"lines": {
"object": "list",
"data": [
{
"id": "cnli_1MxvRqLkdIwHu7ixFpdhBFQf",
"object": "credit_note_line_item",
"amount": 1099,
"amount_excluding_tax": 1099,
"description": "T-shirt",
"discount_amount": 0,
"discount_amounts": [],
"invoice_line_item": "il_1MxvRlLkdIwHu7ixnkbntxUV",
"livemode": false,
"quantity": 1,
"tax_amounts": [],
"tax_rates": [],
"type": "invoice_line_item",
"unit_amount": 1099,
"unit_amount_decimal": "1099",
"unit_amount_excluding_tax": "1099"
}
],
"has_more": false,
"url": "/v1/credit_notes/cn_1MxvRqLkdIwHu7ixY0xbUcxk/lines"
},
"livemode": false,
"memo": null,
"metadata": {},
"number": "C9E0C52C-0036-CN-01",
"out_of_band_amount": null,
"pdf": "https://pay.stripe.com/credit_notes/acct_1M2JTkLkdIwHu7ix/test_YWNjdF8xTTJKVGtMa2RJd0h1N2l4LF9Oak9FOUtQNFlPdk52UXhFd2Z4SU45alpEd21kd0Y4LDcyMjkxNzU50200cROQsSK2/pdf?s=ap",
"reason": null,
"refund": null,
"shipping_cost": null,
"status": "issued",
"subtotal": 1099,
"subtotal_excluding_tax": 1099,
"tax_amounts": [],
"total": 1099,
"total_excluding_tax": 1099,
"type": "pre_payment",
"voided_at": null
}