Subscription invoices

Learn how to understand and manage subscription invoices, the basis for recurring charges.

Invoices are a core resource in Stripe, representing the amount a customer owes. Stripe generates an invoice for every period in a subscription’s billing cycle. You can also manually generate invoices through the Dashboard or API for off-cycle or one-time payments.

See the Stripe Invoicing documentation for more details about how invoicing works.

Subscription invoice lifecycle

The following sections describe how an invoice is handled throughout a subscription lifecycle. See the invoicing documentation for more details about the invoicing lifecycle.

New subscription invoices

When you subscribe a customer, Stripe:

Creates an invoice.
Finalizes the invoice.

If the payment succeeds on a subscription’s first invoice or the invoice does not require payment, the invoice transitions to status=paid, and the subscription becomes active.

Until the payment succeeds, the invoice status remains open and auto_advance remains false. The subscription status remains incomplete. For guidance on how to handle payment failures for new subscription invoices, refer to the How subscriptions work page.

In certain cases upgrading or downgrading the subscription also creates a new invoice. These invoices set auto_advance=false from the outset.

With a finalized invoice, you cannot add invoice items or make other modifications that affect the amount due. (However, you can still add invoice items to the customer, and these will apply to the next invoice.)

Subscription renewal invoices

When subscriptions renew, Stripe:

Creates an invoice.
Leaves the invoice in a draft state for about an hour.
Attempts to finalize and pay the invoice.
Changes the invoice status to paid if payment succeeds.

When the invoice is created, you’ll receive (via configured webhooks) an invoice.created event. This time, the invoice’s status attribute will be draft, which means that its invoice items are open for modification.

Collecting payment

When an invoice is due, Stripe tries to collect payment by either automatically charging the payment method on file, or emailing the invoice to customers.

Retrying payments

Stripe offers several options for dealing with failed payments, including machine-learning powered Smart retries.

Manage subscription invoices

The following sections describe how to perform basic actions on invoices in the Dashboard. For more options around using invoices, see the managing invoices guide.

Create an invoice

To create and send an invoice, complete the following steps:

You can type “invoice.new” into the address bar of any browser to jump straight to the Invoice Editor.

In the Dashboard, click Create Invoice or press N. Whenever you exit the Invoice Editor, Stripe saves a draft. To delete a draft invoice, click the overflow menu (
) next to an invoice on the Invoices page.
Select Add new customer and enter the customer’s name. (You can optionally add an email address and additional details.) Click Save customer.
Select Add one-time item to create a single, one-time item. To save a product for future use, select Create new product.
Enter the Quantity and Price for your new item or product.
(Optional) Click Item taxes and coupons if you need to add a tax rate or coupon.
Use the Dashboard to create a tax rate or coupon.
(Optional) Use the Memo box to provide more information to your customer. You can edit the memo on an invoice by clicking the Edit memo button in its details page.
Select one of the following invoice delivery options:
- Automatically charge a payment method on file—Immediately charges the invoice amount to your customer’s payment method that you have on file.
- Send invoice or payment page link manually—Provides a payment link for you to send to customers after you confirm the invoice.
- Email invoice with link—Enables Stripe to send an email with a payment page and an invoice PDF.
- Email invoice without link—Enables Stripe to send an invoice PDF only.
Click Review invoice and decide whether you want to include additional emails or continue editing. Send the invoice.

Create an invoice with the Dashboard

Edit an invoice

With the Dashboard, you can duplicate an invoice and modify the new copy. When you duplicate an invoice, Stripe copies all of the information on the original invoice except for credit notes, deleted (or archived) products, prices, coupons, discounts, and tax rates. If you made a mistake on an invoice you already created, duplicate it, make your corrections, and then send the new invoice. Remember to void the incorrect invoice as well.

You can change the status of an open invoice in the Dashboard by going to its details page and choosing More > Change Invoice Status.

To duplicate an invoice, view your invoices and click the overflow menu (

) for the invoice you want to duplicate. Click Duplicate invoice to create, edit, and then send the new invoice.

Duplicate an invoice from the Dashboard

Preview upcoming invoices

The Retrieve an invoice API call provides a mechanism for viewing an existing invoice, but Stripe also provides an endpoint for previewing the next upcoming invoice. This preview reflects the base price, pending invoice items, discounts, and any existing customer credit balance.

When fetching the preview, you can also model what the invoice would look like if you changed the subscription in one of these ways:

Swapping the underlying price.
Altering the quantity.
Applying a trial period.
Adding a coupon.

Customize invoices

You can customize invoices in several ways, including:

Adding extra items to a future invoice
- Increasing the frequency of invoices
Adding items to a customer’s first invoice
Adding items to a draft subscription invoice
Generating an invoice outside of the subscription cycle
Pausing a subscription invoice for review

Add extra invoice items to a future invoice

You can add up to 250 invoice items to an invoice. To add extra invoice items to the next invoice in the cycle:

curl https://api.stripe.com/v1/invoiceitems \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
  -d price=price_CBb6IXqvTLXp3f \
  -d customer=cus_4fdAW5ftNQow1a

These one-off items are added to the next invoice created for this customer. To make sure this is added to a specific subscription, use the optional subscription parameter to apply it to that subscription.

Invoice pending items more frequently

Other than changing the billing cycle, there are a few ways to invoice these items without adjusting the normal subscription cycle:

Create a one-off invoice for the customer.
Charge a subscription whenever the amount due reaches a threshold.
Use pending_invoice_item_interval to specify an interval for how often to bill for any pending invoice items. This is equivalent to having Stripe create a one-off invoice for the subscription on a recurring basis.

Add an extra charge or discount on a subscription’s first invoice

Include a one-time charge or discount to the first subscription invoice by using add_invoice_items with one-time price:

Terminal

curl https://api.stripe.com/v1/subscriptions \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{ CUSTOMER_ID }}" \
  -d "items[0][price]"="{{ RECURRING_PRICE_ID }}" \
  -d "add_invoice_items[0][price]"="{{ PRICE_ID }}" \
  -d "payment_behavior"="default_incomplete"

If you’re using Checkout to create subscriptions, add extra charges by specifying line_items with the client and server integration.

Add invoice items to a draft subscription invoice

When a subscription renews and creates an invoice, Stripe sends the invoice.created webhook event. Stripe waits approximately one hour before finalizing the invoice and attempting payment or sending an email.

During that delay, the invoice is a draft and is editable. It’s possible to create invoice items on that invoice. Be certain to provide the invoice parameter when creating these invoice items, otherwise they will be added as pending items and swept up into the next subscription period.

These invoice items behave slightly differently than invoice items automatically generated by Stripe:

Pending invoice items are always charged when the billing period ends for any subscription that is canceled. Canceling a customer’s subscription means only that the customer isn’t billed again if no invoice items exist.
Pending invoice items are not prorated when a customer’s subscription is changed.

If there are pending invoice items that remain even after a subscription is canceled, Stripe will generate an invoice and will attempt to bill the customer for these items at the end of the next billing period. These invoice items are (similarly) not prorated when a subscription is changed.

Generate an invoice for subscription items outside the billing cycle

You can invoice pending invoice items outside of the regular billing cycle by generating a one-off invoice. Generating a one-off invoice pulls in any pending invoice items that would have been added to the regularly scheduled invoice.

When you manually generate an invoice, Stripe does not apply the tax rates you may have established on the subscription. If taxes should apply, you must explicitly add the tax rates to the invoice.

Pausing a subscription invoice for review

Rather than automatically attempting payment at the end of a billing period, you can pause the invoice for review or corrections. To pause an invoice:

Pause automatic collection within one hour of receiving the invoice.created event. You can do this by setting auto_advance=false in the API, or by going to Settings in the Dashboard and clicking Subscriptions and emails. Locate the pause payment section, and click Set up to make changes. This feature prevents Stripe from automatically attempting payment from your customer for the invoice amount, and from emailing the invoice.
Review the invoice.
Once you are ready to attempt payment, resume automatic collection. You can do so either by setting auto_advance=true through the API, or by updating the pause payment options in the Dashboard.