— No Results

    Subscription invoices

    Learn how to manipulate subscription invoices, the basis for recurring charges.

    For every period in a Subscription’s billing cycle, Stripe generates an invoice that represents the amount owed. If an amount is due, Stripe tries to collect payment by either automatically charging the payment method on file, or sending the invoice to customers via email.

    New subscription invoices

    When you subscribe a customer, Stripe:

    • Creates an invoice.
    • Finalizes the invoice.
    • Attempts to pay the invoice, updating the invoice status to paid if successful.

    If the payment succeeds on a subscription’s first invoice, or if no payment is required, the invoice is marked as status=paid, and the subscription is created.

    If the payment fails, the invoice status is set to open, the invoice auto_advance is set to false from the outset, and the subscription is created with a status set to incomplete. For guidance on how to handle payment failures for new subscription invoices, refer to the How subscriptions work page.

    Any API call that results in a new subscription, such as upgrading or downgrading the subscription, also creates a new invoice that is set to 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.

    Adding extra invoice items to a future 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

    stripe invoiceitems create \
  --price={{ PRICE_ID }} \
  --customer={{ CUSTOMER_ID }}

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::InvoiceItem.create({
  price: 'price_CBb6IXqvTLXp3f',
  customer: 'cus_4fdAW5ftNQow1a',
})

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.InvoiceItem.create(
  price='price_CBb6IXqvTLXp3f',
  customer='cus_4fdAW5ftNQow1a',
)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\InvoiceItem::create([
    'price' => 'price_CBb6IXqvTLXp3f',
    'customer' => 'cus_4fdAW5ftNQow1a',
]);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

InvoiceItemCreateParams params =
  InvoiceItemCreateParams.builder()
    .setPrice("price_CBb6IXqvTLXp3f")
    .setCustomer("cus_4fdAW5ftNQow1a")
    .build();

InvoiceItem invoiceItem = InvoiceItem.create(params);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.invoiceItems.create({
  price: 'price_CBb6IXqvTLXp3f',
  customer: 'cus_4fdAW5ftNQow1a',
});

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.InvoiceItemParams{
  Price: stripe.String("price_CBb6IXqvTLXp3f"),
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
}
ii, _ := invoiceitem.New(params)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new InvoiceItemCreateOptions {
    Price = "price_CBb6IXqvTLXp3f",
    Customer = "cus_4fdAW5ftNQow1a",
};
var service = new InvoiceItemService();
InvoiceLineItem invoiceItem = service.Create(options);

    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.

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

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

    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 }}"

    stripe subscriptions create \
  -d customer={{ CUSTOMER_ID }} \
  -d items[0][price]={{ RECURRING_PRICE_ID }} \
  -d add_invoice_items[0][price]={{ PRICE_ID }}

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Subscription.create({
  customer: '{{ CUSTOMER_ID }}',
  items: [{
    price: '{{ RECURRING_PRICE_ID }}',
  }],
  add_invoice_items: [{
    price: '{{ PRICE_ID }}',
  }],
})

    # Set your secret key. Remember to switch to your live secret key in production!
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Subscription.create(
  customer="{{ CUSTOMER_ID }}",
  items=[{
    'price': '{{ RECURRING_PRICE_ID }}'
  }],
  add_invoice_items=[{
    'price': '{{ PRICE_ID }}'
  }]
)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

$subscription = \Stripe\Subscription::create([
  'customer' => '{{ CUSTOMER_ID }}',
  'items' => [[
  'price' => '{{ RECURRING_PRICE_ID }}',
  ]],
  'add_invoice_items' => [[
    'price' => '{{ PRICE_ID }}'
  ]],
]);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

SubscriptionCreateParams params =
  SubscriptionCreateParams.builder()
    .setCustomer("{{ CUSTOMER_ID }}")
    .addItem(
      SubscriptionCreateParams.Item.builder()
       .setPrice("{{ RECURRING_PRICE_ID }}")
       .build())
    .addAddInvoiceItem(
      SubscriptionCreateParams.AddInvoiceItem.builder()
        .setPrice("{{ PRICE_ID }}")
        .build())
    .build();

Subscription subscription = Subscription.create(params);

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

await stripe.subscriptions.create({
  customer: '{{CUSTOMER_ID }}',
  items: [{
    price: '{{ RECURRING_PRICE_ID }}'
  }],
  add_invoice_items: [{
    price: '{{ PRICE_ID }}',
  }],
});

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SubscriptionParams{
  Customer: stripe.String("{{ CUSTOMER_ID }}"),
  Items: []*stripe.SubscriptionItemsParams{
    {
      Price: stripe.String("{{ RECURRING_PRICE_ID }}"),
    },
  },
  AddInvoiceItems: []*stripe.SubscriptionAddInvoiceItemParams{
    {
      Price: stripe.String("{{ PRICE_ID }}"),
    },
  },
}
s, _ := sub.New(params)

    // Set your secret key. Remember to switch to your live secret key in production!
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.ApiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

var options = new SubscriptionCreateOptions
{
  Customer = "{{ CUSTOMER_ID }}",
  Items = new List<SubscriptionItemOptions>
  {
    new SubscriptionItemOptions
    {
      Price = "{{ RECURRING_PRICE_ID }}",
    },
  },
  AddInvoiceItems = new List<SubscriptionAddInvoiceItemOptions>
  {
    new SubscriptionAddInvoiceItemOptions
    {
      Price = "{{ PRICE_ID }}",
    },
  },
};
var service = new SubscriptionService();
Subscription subscription = service.Create(options);

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

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

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

    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:

    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 pressing the Dashboard’s Turn off automatic billing button. This prevents Stripe from automatically attempting payment from your customer for the invoice amount, and from sending the invoice via email.
    2. Review the invoice.
    3. 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 clicking the Dashboard’s Turn on automatic billing button.

    Was this page helpful?
    Feedback about this page?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions? Contact us.

    Developer tutorials on YouTube.

    On this page