Subscription Invoices

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

Subscriptions at Stripe are charged through invoices. For every period in a billing cycle, we generate an invoice that represents the amount the customer owes.

Subscription invoices are prebilled, meaning customers pay at the start of a billing cycle. Assuming an amount is due on an invoice, we then attempt to charge the customer using a previously stored payment method (e.g., a credit card).

Stripe generates and pays invoices automatically for subscriptions, per your subscription settings. But you may want to familiarize yourself with:

Adding invoice items
The states an invoice can be in
How to preview an upcoming invoice
Manually generating invoices

Adding invoice items

The total amount due on an invoice is the sum of its invoice items, which are listed as separate line items. The invoices Stripe generates automatically includes invoice items such as the base plan cost or a proration (after changing a subscription). But you can add more invoice items to change the amount the customer will be charged.

Any positive invoice item amount—an integer in the smallest currency unit (e.g., cents or Yen)—increases the total of the applicable invoice. To discount an invoice, use a negative amount or apply a coupon.

By default, invoice items are always added to the next invoice to be charged. For example, if a customer is billed on the 1st of each month, any invoice item generated during the month is added to the invoice generated on the 1st of the following month. Consequently, an invoice always reflects the cost of the subscription for the upcoming billing period plus any invoice items from the previous billing period.

You can also create invoice items at any point in the billing cycle, and you can create up to 250 invoice items per invoice:

curl https://api.stripe.com/v1/invoiceitems \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -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_BQokikJOvBiI2HlWgH4olfQ2"

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

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_BQokikJOvBiI2HlWgH4olfQ2");

\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_BQokikJOvBiI2HlWgH4olfQ2";

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_BQokikJOvBiI2HlWgH4olfQ2");

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

params := &stripe.InvoiceItemParams{
  Amount: 1000,
  Currency: "usd",
  Customer: "cus_4fdAW5ftNQow1a",
  Description: "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_BQokikJOvBiI2HlWgH4olfQ2");

var options = new StripeInvoiceItemCreateOptions {
    Amount = 1000,
    Currency = "usd",
    Customer = "cus_4fdAW5ftNQow1a",
    Description = "One-time setup fee",
};
var service = new StripeInvoiceItemService();
StripeInvoiceItem invoiceItem = service.Create(options);

The customer, amount, and currency parameters are required. You can optionally include an invoice parameter to apply the invoice item to a specific invoice.

When Stripe automatically generates an invoice for a recurring payment, your site is notified via webhooks (an invoice.created event). Stripe waits approximately an hour before attempting to pay that invoice. In that time, you can add invoice items to the recently-created invoice so that they are covered by the forthcoming payment. Be certain to provide the invoice parameter, though, or else the invoice item is added to the next 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 created invoice item will be attached to the customer and automatically included in the first invoice created.

Invoice items have some unique behaviors:

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

New subscription invoices

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

Creates an invoice
Attempts to pay the invoice
Closes the invoice

The first invoice on a subscription is effectively closed from the moment it’s created. If the payment succeeds or no payment is required, the invoice is also marked as paid and the subscription is created. If the payment fails, the subscription attempt fails, too, and no invoice or subscription exists.

Any API call that results in a new subscription, such as upgrading or downgrading the plan, also creates a new invoice that is closed from the onset.

With a closed invoice, you cannot add invoice items or make other modifications that affect the amount due. (You can still add invoice items to the customer, however, which 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. Stripe:

Creates an invoice
Leaves the invoice open for about an hour
Attempts to pay the invoice
Closes the invoice if the payment succeeds

When the invoice is created, you’ll receive via webhooks an invoice.created event. This time, the invoice’s closed attribute will be false, which means it’s open for modification via invoice items.

Previewing upcoming invoices

The retrieve 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 see what the invoice would look like if you changed the subscription by:

Swapping the underlying plan
Altering the quantity
Applying a trial period
Adding a coupon

The previewing prorations documentation provides an example usage.

Manually generating Subscription invoices

At the end of a billing cycle, Stripe automatically creates an invoice containing both a line item for the customer’s subscription (going forward) and any invoice items that had been left pending on the customer. However, 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 (e.g., upgrading a user from a $10 per month plan to a $20 per month plan mid-month triggers proration invoice items in the net of approximately $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 request creation of an invoice after upgrading.

You manually generate an invoice via the API using the create invoice method or from the Dashboard, using the Invoice Now button in the Pending Invoice Items pane.

curl https://api.stripe.com/v1/invoices \
   -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
   -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_BQokikJOvBiI2HlWgH4olfQ2"

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

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_BQokikJOvBiI2HlWgH4olfQ2");

\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_BQokikJOvBiI2HlWgH4olfQ2";

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_BQokikJOvBiI2HlWgH4olfQ2");

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

params := &stripe.InvoiceParams{
  Customer: "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_BQokikJOvBiI2HlWgH4olfQ2");

var options = new StripeInvoiceCreateOptions();
var service = new StripeInvoiceService();
StripeInvoice invoice = service.Create("cus_4fdAW5ftNQow1a", options);

Note that manually creating an invoice does not lead to a synchronous attempt to pay the invoice. Payment is automatically attempted between 1 and 2 hours after the invoice is created. You can also request immediate payment of an invoice at any time using a pay invoice API call.