For information about working with credit notes using the Dashboard, see Issue credit notes.
When you create a credit note, you can apply credit amounts in three ways:
- Discount a fixed amount from an invoice line item.
- Discount a quantity from an invoice line item. The total discount is the discount quantity times the unit price of that line item.
- Apply a discount to the total invoice amount by adding a custom discount line item with a description, quantity, and unit price. The total discount is the quantity times the unit price.
We recommend discounting invoice line items when possible, since it associates each credit with a line item. Adding a custom discount line item can make reporting and tracking difficult, because the credit isn’t associated with a real invoice line item.
You can’t combine discount types on an invoice line item. For example, if you discount a line item quantity, then a future credit note can only discount that line item by quantity, not by amount. If you discount a line item amount, then a future credit note can only discount that line item by amount, not by quantity.
Credit notes for open invoices
When you create a custom line item on a credit note for an
open invoice, the
amount_due on the invoice decreases based on the
custom_line_items in the credit note. This is in addition to any adjustments you make to existing
invoice_line_items. For example, if the amount due on an
open invoice is 100 USD and you create a
unit_amount=2000, the new amount due on the invoice is 80 USD.
On an invoice, credit notes appear as items after applying discounts and taxes—so they’re a post-tax adjusted amount. We calculate the invoice amount due using the following order:
- Sum of invoice line items
- Pre-tax invoice total
- Customer credit balance
- Credit notes applied (to gross amount due)
- New amount due
If applying a credit note to an invoice changes the amount due to zero, the invoice automatically transitions into the
paid state. If you want to change the quantity or amount of an existing line item, pass the invoice ID, the line item ID, and the new quantity or amount. When a line item has a quantity and an amount, you can only update the quantity. Otherwise, you can only change the amount. The example below adjusts the quantity to two:
To create a custom line item on the credit note, pass the invoice ID, description, quantity, and unit amount. You can (optionally) set a tax rate as well. This example creates a custom line item on the credit note for 10 USD:
Credit notes for paid invoices
When you create a credit note for a
paid invoice, the amount due on the invoice doesn’t change. Instead, the user can choose one or more of the following options:
|Create a refund||Refund the invoice’s charge back to the customer’s payment method.|
|Link a refund||Link an existing refund for the invoice’s charge.|
|Credit the customer credit balance||Credit the customer credit balance, which is automatically applied to their future invoices.|
|Credit outside of Stripe||Credit the invoice for an amount made in an adjustment outside of Stripe.|
In the following example, the credit note creates a refund:
Here, the credit note creates a credit to the customer credit balance:
You can also combine multiple parameters. Funds that are left over after subtracting the refund and credit amounts from the invoice
amount results in a credit outside of Stripe, usually with cash or a check:
Voiding credit notes
You can void a credit note only if it’s on an open invoice. Voiding a credit note reverses its adjustment, increasing the amount due on the invoice by the amount of the credit note. To void a credit note: