Working with Invoices

    Learn how to manipulate invoices, the basis for recurring charges. If you need help after reading this, check out our answers to common questions or chat live with other developers in #stripe on freenode.

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

    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.

    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.

    You can also create invoice items at any point in the billing cycle, of course, and you can create as many invoice items as you want:

    curl https://api.stripe.com/v1/invoiceitems \
       -u sk_test_BQokikJOvBiI2HlWgH4olfQ2: \
       -d customer=cus_3R1W8PG2DmsmM9 \
       -d amount=1000 \
       -d currency=usd \
       -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(
      :customer => "cus_3R1W8PG2DmsmM9",
      :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",
      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",
      "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.apiKey = "sk_test_BQokikJOvBiI2HlWgH4olfQ2";
    
    Map<String, Object> params = new HashMap<String, Object>();
    params.put("customer", "cus_3R1W8PG2DmsmM9");
    params.put("amount", 1000);
    params.put("currency", "usd");
    params.put("description", "One-time setup fee");
    
    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({
      customer: "cus_3R1W8PG2DmsmM9",
      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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.InvoiceItemParams{
      Customer: "cus_3R1W8PG2DmsmM9",
      Amount: 1000,
      Currency: "usd",
      Description: "One-time setup fee",
    }
    invoiceItem, err := invoiceItem.New(params)
    

    The customer, amount, and currency parameters are required. You can optionally include an invoice parameter to apply the invoice item to a specific 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

    Invoices, like subscriptions, have meaningful properties that reflect the invoice’s status:

    • attempt_count
    • attempted
    • closed
    • forgiven
    • next_payment_attempt
    • paid

    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

    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:

    • Remains past_due, generating more, open invoices with payment attempts
    • Is marked as unpaid, generating more, closed invoices without payment attempts
    • Is canceled, generating no new invoices

    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:

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

    The previewing prorations documentation provides an example usage.

    Manually generating 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_9CQ7bS9zi2gBTP
    
    # 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_9CQ7bS9zi2gBTP",
    )
    
    # 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_9CQ7bS9zi2gBTP",
    )
    
    // 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(array(
      "customer" => "cus_9CQ7bS9zi2gBTP",
    ));
    
    // 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<String, Object>();
    params.put("customer", "cus_9CQ7bS9zi2gBTP");
    
    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_9CQ7bS9zi2gBTP",
    }, function(err, invoice) {
      // 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.Key = "sk_test_BQokikJOvBiI2HlWgH4olfQ2"
    
    params := &stripe.InvoiceParams{
      Customer: "cus_9CQ7bS9zi2gBTP",
    }
    invoice, err := invoice.New(params)
    

    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:

    1. Close the invoice within one hour of receiving the invoice.created event. This prevents Stripe from automatically charging your customer for the invoice amount.
    2. Review the invoice.
    3. Once you are ready to charge the customer, reopen the invoice.
    4. Finally, pay the invoice.

    Note that once you close the invoice, you must later trigger a payment attempt on it. Simply re-opening the invoice is not enough.

    Next steps

    Congrats! You've learned more about working with invoices. Some documentation you might want to read next: