Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Developer tools
Get started
Payments
Finance automation
Get started
Payments
Finance automation
Platforms and marketplaces
Money management
Overview
Billing
    Overview
    About the Billing APIs
    Subscriptions
      Overview
      Quickstart
      Use cases
      Build your integration
      Subscription features
        Subscription invoices
        Subscription schedules
        Subscription pricing
        Recurring pricing models
        Embed a pricing table
        Start subscriptions
        Set quantities
        Set billing cycles
        Backdate subscriptions
        Subscribe to multiple items
        Set trial periods
        Apply coupons
        Migrate subscriptions to Stripe
        How credit prorations are calculated
        Subscription payments
        Subscription payment methods
        Integrate with third-party payment processing
        Collection methods
        Share a link to update payment details
        Strong Customer Authentication (SCA)
        Manage subscriptions
        Modify subscriptions
        Manage pending updates
      Analytics
    Invoicing
    Usage-based billing
    Connect and Billing
    Tax and Billing
    Quotes
    Revenue recovery
    Automations
    Scripts
    Revenue recognition
    Customer management
    Entitlements
    Test your integration
Tax
Reporting
Data
Startup incorporation
HomeFinance automationBillingSubscriptionsSubscription features

Subscription invoices

Learn how to manage subscription invoices.

Copy page

Invoices are core resources in Stripe, representing the amount a customer owes. Stripe generates an invoice for every period in a subscription billing cycle period. You can also manually generate invoices through the Dashboard or API for off-cycle or one-time payments. Learn more about the lifecycle for standalone invoices and subscription-generated invoices.

Subscription invoice lifecycle

The following sections describe how Stripe handles an invoice throughout a subscription 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 doesn’t 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. Learn how to resolve payment failures for new subscription invoices that require a payment method.

In some cases, upgrading or downgrading the subscription also creates a new invoice. We turn off auto_advance for these invoices from the outset.

With a finalized invoice, you can’t add invoice items or make other modifications that affect the amount due. However, you can still add invoice items to the customer. The added items 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 with the default payment method.

  • Changes the invoice status to paid if payment succeeds.

When Stripe creates an invoice, you receive an invoice.created event at your configured webhook endpoint. In this case, the attribute of the invoice status is draft, which means that its invoice items are open for modification.

Collect 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.

Retry 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.

Create an invoice

Stripe automatically creates an invoice for subscriptions at the end of each billing cycle. We finalize and send the invoice in one hour. Before the invoice is finalized, you can edit it. Read more about making changes in the Invoice details page.

Preview upcoming invoices

The Retrieve an invoice API provides a mechanism for viewing an existing invoice. Stripe also provides an endpoint for creating a preview 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.

Update the first invoice of a subscription

How you edit the first invoice of a subscription depends on the setting for the customer’s payment method for the subscription. If unsure, you can check the payment method setting using the API or the Dashboard.

To check subscription payment method using the API, check the value of collection_method on the Subscriptions object for the customer. A value of send_invoice means Stripe emails the customer their invoice. A value of charge_automatically means Stripe charges the customer on your behalf using their default payment method.

To check subscription payment method in the Dashboard, open the Subscriptions page. Then, click the subscription you want to check to open it’s detailed view. In the Subscription details section, the Billing method field value defines the payment method: Charge default payment method or Send invoice.

For customers that receive invoices, you have a one hour period after creation before Stripe finalizes the subscription. Within this timeframe you can make necessary changes to the subscription, like changing amount or line items, adding a description or metadata, and so on.

After the initial hour, you can no longer make updates. Stripe emails the invoice to the customer to collect subscription payment.

Customize invoices

You can customize invoices in several ways, including:

  • Add extra items to a future invoice
  • Increase the frequency of invoices
  • Add items to a customer’s first invoice
  • Add items to a draft subscription invoice
  • Generate an invoice outside of the subscription cycle
  • Pause a subscription invoice for review
  • Issue a subscription invoice with configurable item prices

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:

Command Line
cURL
curl https://api.stripe.com/v1/invoiceitems \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "pricing[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.
  • 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 on a subscription’s first invoice

Include a one-time charge to the first subscription invoice using add_invoice_items:

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

Caution

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. You can create invoice items on that invoice. Make sure to provide the invoice parameter when you create these invoice items. Otherwise, they’re added as pending items and are included in 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 canceled subscription. Canceling a customer’s subscription prevents them from being billed again if no invoice items exist.

  • Pending invoice items aren’t prorated when a customer’s subscription changes.

If pending invoice items remain after a subscription cancels, Stripe generates an invoice and attempts to bill the customer for them at the end of the next billing period. These invoice items are (similarly) not prorated when a subscription changes.

Manage pending invoice items

You can see a customer’s pending invoice items by navigating to the Customers page, and clicking on their name. If the customer has a pending invoice item, it appears under Pending invoice items. An invoice item appears as pending if it’s not attached to any invoice.

Under Pending invoice items, you can also choose to create a new invoice item, or instantly invoice everything listed. When you click Invoice now, a dialog appears that lets you select whether to charge the default source or email the invoice to the customer. Additionally, the dialog gives you the option to calculate tax automatically.

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.

Caution

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.

Pause 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:

  1. 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 Subscriptions and emails in the Dashboard. 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.

  2. Review the invoice.

  3. After you’re ready to charge the customer, resume automatic collection. You can this by either setting auto_advance=true, or by updating the pause payment options in the Dashboard.

Issue a subscription invoice with configurable item prices

You can issue invoices with line item prices that exclude inclusive tax. Tax-exclusive prices are only shown in the invoice PDF. That means, when using inclusive tax, the Hosted Invoice Page and invoice emails show tax-inclusive prices. You can define the settings for net prices in the Dashboard or API.

  • Include inclusive tax—The invoice PDF displays line item prices including the inclusive tax. (This is the default.)
  • Exclude tax—The invoice PDF displays line item prices excluding tax.

Order precedence

If you set a default for line item prices at the customer level, it takes precedence over account-level settings.

Subscription metadata

After a subscription creates an invoice, it includes the subscription’s metadata in the following ways:

  • The invoice’s subscription_details.metadata attribute always contains the subscription’s metadata at the time of invoice creation, even if the subscription metadata is later modified.
  • The metadata attribute of invoice line items with type=“subscription” reflects the most recent subscription metadata at the time of retrieving the invoice, meaning it might differ from the metadata at the time of invoice creation.
  • Invoice line items with type=“invoiceitem” don’t contain the subscription’s metadata.

When you modify a subscription invoice line item’s metadata directly, either with the invoice line update or the bulk invoice line update endpoint, the update request declares the invoice line item metadata. Any “inherited” Subscription metadata isn’t preserved implicitly.

Subscription item metadata isn’t automatically propagated to any other Stripe objects.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc