Generate credit notes programmatically
Use the Invoicing API to adjust or refund finalized invoices with credit notes.
To adjust the balance of an open, paid, or uncollectible invoice, generate a credit note.
Note
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.
Note
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_item 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 custom_line_item with quantity=1 and unit_amount=2000, the new amount due on the invoice is 80 USD.
When using custom_line_item, you must provide the credit amount using unit_amount (or unit_amount_decimal) and quantity, instead of a flat amount. You can describe the line item with description, and apply taxes using either tax_rates or tax_amounts, but not both.
On an invoice, credit notes appear as items after applying discounts and taxes, making them a post-tax adjusted amount. We calculate the invoice amount due using the following order:
- Sum of invoice line items
- Discounts
- Pre-tax invoice total
- Taxes
- 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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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:
| Action | Description |
|---|---|
| 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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Here, the credit note creates a credit to the customer credit balance:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
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:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Crediting negative line items
You can credit a negative amount to a negative invoice_line_item using either the amount or quantity parameters.
For example, if you have an open invoice with two line items:
- a positive line item with quantity=1 and unit _ amount=10000
- and a negative line item with quantity=1 and unit _ amount=-5000 .
This example uses the amount parameter to credit the full amount of both line items:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
This example uses the quantity parameter to do the same:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
The following restrictions apply:
- The total amount of the credit note must remain positive.
- The total amount credited to a negative line item must be negative.
- The total amount credited to a negative line item can’t be less than the line item amount.
You also can’t credit a negative amount on a custom_line_item. We only support negative amounts on invoice_line_items.