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

    This page covers:

    New subscription invoices

    When you subscribe a customer to a plan, the API call immediately:

    • 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 subscription attempt fails as well, and no invoice or subscription is created.

    Any API call that results in a new subscription, such as upgrading or downgrading the plan, 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 a subscription is updated automatically, instead of via the API, the invoice behavior is a bit different. In these cases, 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 to a future invoice

    In the middle of a billing period, you might want to add more invoice items to the next invoice.

    You can also create invoice items at any point in the billing cycle:

    curl https://api.stripe.com/v1/invoiceitems \
   -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
   -d amount=1000 \
   -d currency=usd \
   -d customer=cus_4fdAW5ftNQow1a \
   -d description="One-time setup fee"

    # Set your secret key: remember to change this 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({
    amount: 1000,
    currency: 'usd',
    customer: 'cus_4fdAW5ftNQow1a',
    description: 'One-time setup fee',
})

    # Set your secret key: remember to change this 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(
  amount=1000,
  currency='usd',
  customer='cus_4fdAW5ftNQow1a',
  description='One-time setup fee',
)

    // Set your secret key: remember to change this 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([
    'amount' => 1000,
    'currency' => 'usd',
    'customer' => 'cus_4fdAW5ftNQow1a',
    'description' => 'One-time setup fee',
]);

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

Map<String, Object> params = new HashMap<>();
params.put("amount", 1000);
params.put("currency", "usd");
params.put("customer", "cus_4fdAW5ftNQow1a");
params.put("description", "One-time setup fee");
InvoiceItem invoiceItem = InvoiceItem.create(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

stripe.invoiceItems.create({
  amount: 1000,
  currency: 'usd',
  customer: 'cus_4fdAW5ftNQow1a',
  description: 'One-time setup fee',
});

    // Set your secret key: remember to change this 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{
  Amount: stripe.Int64(1000),
  Currency: stripe.String(string(stripe.CurrencyUSD)),
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
  Description: stripe.String("One-time setup fee"),
}
ii, _ := invoiceitem.New(params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

var options = new InvoiceItemCreateOptions {
    Amount = 1000,
    Currency = "usd",
    CustomerId = "cus_4fdAW5ftNQow1a",
    Description = "One-time setup fee",
};
var service = new InvoiceItemService();
InvoiceLineItem invoiceItem = service.Create(options);

    You can optionally use an subscription parameter to apply the invoice item to a specific subscription.

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

    Should you need to include a one-time charge or discount to the first subscription invoice, you can do so by adding an invoice item to the customer before creating the subscription. (The above code would work, as it doesn’t specify an invoice.) The resulting invoice item will be attached to the customer and automatically included in the first invoice created.

    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 attempting to finalize the invoice and automatically collect payment for it.

    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 to the next subscription period.

    If you have generated invoice items for a subscription, these invoice items behave slightly differently than invoice items automatically generated by Stripe:

    • User-generated invoice items are always charged when the billing period ends, even if the subscription is canceled. Canceling a customer’s subscription means only that the customer isn’t billed again if no invoice items exist.
    • User-generated 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 plan cost, 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 plan
    • Altering the quantity
    • Applying a trial period
    • Adding a coupon

    Generating an invoice for subscription items outside the billing cycle

    At the end of a billing cycle, Stripe automatically creates an invoice containing both a line item for the customer’s subscription (future charges) and any invoice items that have been left pending on the customer. When the customer has pending invoice items, you can also request that an invoice be generated at any time. Generating a one-off invoice does not affect the customer’s standard billing schedule, but it does pull in any pending invoice items that would have been added to the regularly scheduled invoice.

    Manually generating invoices can be helpful when you want to request immediate payment of prorations created when you upgraded your customer’s subscription. For example, upgrading a user from a $10-per-month plan to a $20-per-month plan, mid-month, triggers proration invoice items for approximately a net $5.

    However, by default, these prorations simply remain pending on the customer until the end of the month. If you’d like the customer to be billed immediately, you can always create a one-off invoice after upgrading.

    You manually generate an invoice from the Dashboard’s Customers section, using the Pending invoice items pane’s Invoice Now button; or from the API, using the Create an invoice method:

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

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

Stripe::Invoice.create({
    customer: 'cus_4fdAW5ftNQow1a',
})

    # Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

stripe.Invoice.create(
  customer='cus_4fdAW5ftNQow1a',
)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

\Stripe\Invoice::create([
    'customer' => 'cus_4fdAW5ftNQow1a',
]);

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

Map<String, Object> params = new HashMap<>();
params.put("customer", "cus_4fdAW5ftNQow1a");
Invoice invoice = Invoice.create(params);

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
var stripe = require("stripe")("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

stripe.invoices.create({
  customer: 'cus_4fdAW5ftNQow1a',
});

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

params := &stripe.InvoiceParams{
  Customer: stripe.String("cus_4fdAW5ftNQow1a"),
}
inv, _ := invoice.New(params)

    // Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

var options = new InvoiceCreateOptions {
    CustomerId = "cus_4fdAW5ftNQow1a",
};
var service = new InvoiceService();
Invoice invoice = service.Create(options);

    Holding a subscription invoice for review

    Rather than automatically attempting payment at the end of a billing period, you can hold the invoice for review or corrections. To hold 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.

    Questions?

    We're always happy to help with code or other questions you might have! Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    Was this page helpful? Yes No

    Send

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