Invoicing Customers
Subscriptions on Stripe are charged through invoices. We generate an Invoice object that represents the amount the customer owes and then attempt to charge the customer that amount. Note that this kind of invoice isn’t actually sent to the customer but is instead paid automatically in Stripe. A successful payment of the invoice results in an active subscription.
When you first subscribe a customer to a plan, an invoice is immediately generated. Assuming that the plan does not have a free trial period (i.e., the customer must pay immediately), Stripe will immediately attempt to charge the customer for that invoice amount. The invoice is then closed, denoted by the closed parameter with the value of true.
Once an invoice is closed, it cannot be modified or have additional items added to it as the customer has already been charged. An invoice’s metadata can be updated at any time.
When a subscription period is up (e.g., one month or two weeks or whatever period your plan uses), Stripe will automatically generate another invoice. Unlike the first invoice, Stripe will wait approximately one hour before attempting to charge subsequent invoices so that you can make adjustments to the invoice if needed (e.g., add additional charges to the invoice, or add credits that offset the invoice amount). The invoice is considered open during this time, and its closed parameter has the value false.
In order to make adjustments to an invoice, your site will need to be aware of the invoice’s creation by using webhooks, which listen for events.
Adding invoice items
Invoice items are the most common way to change the amount the customer will be charged. Invoice items appear on an invoice as separate line items.
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.
As another example, when Stripe automatically generates an invoice for a recurring payment, your site will be notified of the invoice via webhooks (an invoice.created event). Stripe will wait approximately an hour before attempting to pay that invoice. In that time, you can add invoice items to the recently-created invoice.
You can create an invoice item at any point in time, and you can create as many invoice items as you want:
# 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(
:customer => "cus_3R1W8PG2DmsmM9",
:invoice => "in_3ZClIXPhhwkNsp"
:amount => 1000,
:currency => "usd",
: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(
customer="cus_3R1W8PG2DmsmM9",
invoice="in_3ZClIXPhhwkNsp"
amount=1000,
currency="usd",
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(array(
"customer" => "cus_3R1W8PG2DmsmM9",
"invoice" => "in_3ZClIXPhhwkNsp",
"amount" => 1000,
"currency" => "usd",
"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
var stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2");
stripe.invoiceItems.create({
customer: "cus_3R1W8PG2DmsmM9",
invoice: "in_3ZClIXPhhwkNsp"
amount: 1000,
currency: "usd",
description: "One-time setup fee"
}, function(err, invoiceItem) {
// asynchronously called
});
// 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> invoiceItemParams = new HashMap<String, Object>();
invoiceItemParams.put("customer", "cus_3R1W8PG2DmsmM9");
invoiceItemParams.put("invoice", "in_3ZClIXPhhwkNsp");
invoiceItemParams.put("amount", 1000);
invoiceItemParams.put("currency", "usd");
invoiceItemParams.put("description", "One-time setup fee");
InvoiceItem.create(invoiceItemParams);
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. Simply use the above code but omit the invoice parameter. The created invoice item will be attached to the customer and automatically included in the first invoice created.
Any positive invoice item amount (an integer in cents) increases the cost of the applicable invoice. To discount an invoice, use a negative amount.
Invoice items have some unique behaviors:
- Invoice items will always be charged when the billing period ends even if the subscription is canceled. Canceling a customer’s subscription only means the customer will not be billed again if no invoice items exist.
- Invoice items are not prorated when a customer’s subscription is changed from one plan to another.
Generating invoices
At the end of a billing cycle, Stripe will automatically create an invoice containing both a line item for the customer’s subscription 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 will not affect the customer’s standard billing schedule, but it will pull in any pending invoice items.
You can do this via the API using the create invoice method or from the dashboard, using the “Invoice Now” button in the Pending Invoice Items pane.
This can be helpful when you want to request immediate payment of prorations that were 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 will trigger proration invoice items in the net of approximately $5). However, by default, these prorations will 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.
Note that creating an invoice does not lead to an synchronous attempt to pay the invoice. However, the invoice will be automatically attempted between and 1 and 2 hours after it is created. You can also request immediate payment of an invoice at any time using pay_invoice.
Holding a renewal for review
Rather than automatically charging the customer for the invoice items at the end of a billing period, you can hold the invoice for a review process. Close the invoice within one hour of receiving the invoice.created event—this will prevent Stripe from automatically charging your customer for the invoice amount.
Once you’ve reviewed the invoice and are ready to charge the customer, you can reopen the invoice and then pay the invoice.