Working with Invoices

What invoices are not

Stripe uses invoices solely as a mechanism for subscriptions. Invoices at Stripe are not documents you generate, send to a customer, and then have them pay.

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, per your subscription settings. But you may want to familiarize yourself with:

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:

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 the forthcoming payment covers it. 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.

Invoice states

The values of these attributes differ for the first invoice on a new subscription, subsequent invoices, and for invoices with payment failures. You can also manually change an invoice’s state.

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.

Invoices with failed payment attempts

Delinquent customers

The delinquent property of the Customer object reflects the success of the most recent invoice payment attempt.

When payment on a subscription renewal invoice fails, the properties of that invoice is dictated by your subscription settings. Each time a payment attempt fails, the attempt_count is incremented and the next_payment_attempt value is set according to your retry settings.

When the maximum number of payment attempts have been made, the subscription:

Once a payment attempt has been made on an invoice, the invoice cannot be modified.

Manual state changes

You can change an invoice’s state by manually marking it as closed or by closing and forgiving it. Subsequent payment attempts are never made on closed or forgiven invoices. Forgiving an invoice instructs us to update the subscription status as if the invoice was successfully paid. Once an invoice has been forgiven, it cannot be unforgiven or reopened.

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:

Manually generating invoices

Taxes and generated invoices

When you manually generate an invoice, Stripe does not apply the taxes you may have established on the subscription. If taxes should apply, manually add the tax on the invoice itself (as a flat amount or percent).

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.

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.

Holding an invoice 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. To do so:

Close the invoice within one hour of receiving the invoice.created event. This prevents Stripe from automatically charging your customer for the invoice amount.