Invoices

    Learn how to customize and send invoices.

    Invoices are the Stripe representation of “amount owed” by your customer. These invoices come in different forms:

    • Invoices can be a one-time bill that you charge your customer.
    • Subscription invoices represent the amount a customer owes on a recurring basis for a Subscription. We generate an invoice every billing cycle. That invoice represents the amount the customer owes for that period.

    You can collect payment on these invoices in two ways:

    • Charged automatically to the source on file.
    • Emailed to a customer for later payment according to specific due date terms.
    • Stripe automatically creates customizable payment pages you can choose to attach to these emailed invoices.
    • With asynchronous payment methods, you can use Stripe’s auto reconciliation logic to automate the process of marking invoices as paid.

    Automatic payment

    Stripe can automatically attempt to pay an invoice if the customer has a payment source. Invoices set to be paid automatically are charged about an hour after creation. You can refer to the invoice lifecycle for more details. When a payment attempt for the invoice fails, Stripe retries payment according to your settings. You can also have Stripe automatically email your customer when an invoice payment fails.

    Stripe does not send an invoice to your customer before attempting automatic payment. You can configure your customer emails settings to send a receipt to your customers after invoices are paid.

    In the API, invoices paid automatically have the billing field set to charge_automatically

    Emailing invoices

    You can email invoices to your customers so they can review their charges or choose their payment method. You can email invoices to your customers through subscriptions, or by creating one-time invoices from the Dashboard. When your customer pays the invoice, it is reconciled automatically.

    When you email an invoice, you have the option of enabling a hosted invoice page to allow your customers to view and pay their invoice online through Stripe.

    Note that emailed invoices follow a slightly different lifecycle than automatically paid invoices.

    To create a subscription that emails invoices to your customer, perform a create subscription request, providing two additional arguments:

    • A billing value of send_invoice (the default value is charge_automatically)
    • A days_until_due value as a positive integer

    The days_until_due value is added to each invoice’s creation date to determine when the invoice becomes past due (if unpaid).

    curl https://api.stripe.com/v1/subscriptions \
       -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
       -d customer=cus_4fdAW5ftNQow1a \
       -d items[0][plan]=plan_CBb6IXqvTLXp3f \
       -d billing=send_invoice \
       -d days_until_due=30
    
    # 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"
    
    subscription = Stripe::Subscription.create({
        customer: 'cus_4fdAW5ftNQow1a',
        items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
        billing: 'send_invoice',
        days_until_due: 30,
    })
    
    # 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"
    
    subscription = stripe.Subscription.create(
      customer='cus_4fdAW5ftNQow1a',
      items=[{'plan': 'plan_CBb6IXqvTLXp3f'}],
      billing='send_invoice',
      days_until_due=30,
    )
    
    // 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");
    
    $subscription = \Stripe\Subscription::create([
        'customer' => 'cus_4fdAW5ftNQow1a',
        'items' => [['plan' => 'plan_CBb6IXqvTLXp3f']],
        'billing' => 'send_invoice',
        'days_until_due' => 30,
    ]);
    
    // 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> item = new HashMap<>();
    item.put("plan", "plan_CBb6IXqvTLXp3f");
    Map<String, Object> items = new HashMap<>();
    items.put("0", item);
    Map<String, Object> params = new HashMap<>();
    params.put("customer", "cus_4fdAW5ftNQow1a");
    params.put("items", items);
    params.put("billing", "send_invoice");
    params.put("days_until_due", 30);
    Subscription subscription = Subscription.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");
    
    const subscription = stripe.subscriptions.create({
      customer: 'cus_4fdAW5ftNQow1a',
      items: [{plan: 'plan_CBb6IXqvTLXp3f'}],
      billing: 'send_invoice',
      days_until_due: 30,
    });
    
    // 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"
    
    items := []*stripe.SubscriptionItemsParams{
      {Plan: stripe.String("plan_CBb6IXqvTLXp3f"),},
    }
    params := &stripe.SubscriptionParams{
      Customer: stripe.String("cus_4fdAW5ftNQow1a"),
      Items: items,
      Billing: stripe.String(string(stripe.InvoiceBillingSendInvoice)),
      DaysUntilDue: stripe.Int64(30),
    }
    subscription, _ := sub.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 items = new List<StripeSubscriptionItemOption> {
        new StripeSubscriptionItemOption {PlanId = "plan_CBb6IXqvTLXp3f"}
    };
    var options = new StripeSubscriptionCreateOptions {
        Items = items,
        Billing = StripeBilling.SendInvoice,
        DaysUntilDue = 30,
    };
    var service = new StripeSubscriptionService();
    StripeSubscription subscription = service.Create("cus_4fdAW5ftNQow1a", options);
    

    When creating subscriptions in the Dashboard, select Email invoices for customer to pay manually under Billing to email invoices to your customer.

    Emailed invoices can also be created with one-time invoices.

    Creating invoices (one-time)

    One-time invoices can be created from the Dashboard. These invoices are created in draft state, while in the draft state you can add line items to the invoice, set a discount, and set a tax percentage.

    When you are done modifying a draft invoice you can either charge the customer automatically or send them an invoice via email. Charging automatically will follow the automatic payment lifecycle and wait an hour after sending a invoice.created webhook before charging the customer.

    If you choose to send your draft invoice it cease to be editable when the invoice is sent. This makes the lifecycle slightly different:

    1. The invoice is sent with a set due date. Both invoice.created and invoice.sent events are sent. The invoice is no longer editable.
    2. When your customer pays the invoice an invoice.payment_succeeded event is sent and the invoice’s paid state is set to true.
    3. If the customer does not pay the invoice before the due date or sends an amount which is not automatically reconciled, the subscription becomes past_due.

    When sending a one-time invoice you will have the option of allowing your customer to view and pay the invoice from a hosted invoice page by selecting that option in the Billing section.

    Hosted invoice page

    When emailing your customer an invoice you can enable a hosted invoice page. This is a Stripe page that allows your customer to view and pay their invoice.

    The hosted invoice page displays the line items, discounts, taxes, payment state, and all available payment methods for the invoice. If you enable “cards” in your billing settings your customer will also have the option of entering credit or debit card payment information to immediately pay and reconcile the invoice.

    You control which payment methods are available to your customers from the Billing settings in Allow customers to pay with. When creating one-time invoices these settings can be overridden in the Billing section.

    Recovery

    When a payment attempt for an automatically paid invoice fails, Stripe attempts to recover the invoice by retrying the charge at a later time. Your retry rules govern how long Stripe will try to recover the invoice and what to do with the subscription if the invoice can’t be recovered.

    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 invoices. Some documentation you might want to read next:

    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.