Create an invoice

    Learn how to create an invoice and bill a customer.

    Overview

    This guide describes how to create an invoice and collect payment. Invoices provide an itemized list of goods and services rendered, which includes the cost, quantity, and taxes. You can also use them as a tool to collect payment.

    Businesses that aren’t subscription based but still need to send invoices to their customers commonly use one-off invoices. For example, a consulting business might send invoices for the time and resources that each consultation uses.

    The Stripe Dashboard is the most common way to create one-off invoices. You can automate this process if you integrate with the API. Click the tab below for the flow you want to follow.

    1 Set up Stripe Server-side

    Use our official libraries for access to the Stripe API from your application:

    Available as a gem:

    sudo gem install stripe

    If you use bundler, you can use this line:

    gem 'stripe', :git => 'https://github.com/stripe/stripe-ruby'

    Available through pip:

    pip install --upgrade stripe

    Alternatively, you can also use easy_install:

    easy_install --upgrade stripe

    The PHP library can be installed via Composer:

    composer require stripe/stripe-php

    Alternatively, you can download the source directly.

    For Gradle, add the following dependency to your build.gradle:

    implementation "com.stripe:stripe-java:{VERSION}"
    (Replace {VERSION} with the actual version number you want to use. You can find the most recent version on Maven Repository or GitHub.)

    For Maven, add the following dependency to your POM:

    <dependency>
      <groupId>com.stripe</groupId>
      <artifactId>stripe-java</artifactId>
      <version>{VERSION}</version>
    </dependency>
    (Replace {VERSION} with the actual version number you want to use. You can find the most recent version on Maven Repository or GitHub.)

    In other environments, manually install the following JARs:

    Install via npm:

    npm install stripe

    Install via go:

    go get github.com/stripe/stripe-go

    Then import the package:

    import (
      "github.com/stripe/stripe-go"
    )

    Install via dotnet:

    dotnet add package Stripe.net
    dotnet restore

    Or using NuGet:

    PM> Install-Package Stripe.net

    2 Create a customer Server-side

    The Customer object represents the customer purchasing your product and is required for creating an invoice.

    curl https://api.stripe.com/v1/customers \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d name="jenny rosen" \
      -d email="jenny.rosen@example.com" \
      -d description="Customer for jenny.rosen@example.com"
    
    # 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'
    
    customer = Stripe::Customer.create(
      name: data['jenny rosen'],
      email: data['jenny.rosen@example.com'],
      description: data['Customer for jenny.rosen@example.com'],
    )
    
    # 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'
    
    customer = stripe.Customer.create(
      name=data['jenny rosen'],
      email=data['jenny.rosen@example.com'],
      description=data['Customer for jenny.rosen@example.com'],
    )
    
    // 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');
    
    $customer = \Stripe\Customer::create([
      "name" => "jenny rosen",
      "email" => "jenny.rosen@example.com",
      "description" => "Customer for jenny.rosen@example.com"
    ]);
    
    // 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> customerParams = new HashMap<String, Object>();
    customerParams.put("name", "jenny rosen");
    customerParams.put("email", "jenny.rosen@example.com");
    customerParams.put("description", "Customer for jenny.rosen@example.com");
    Customer.create(customerParams);
    
    // 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
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    const customer = await stripe.customers.create({
      name: 'jenny rosen',
      email: 'jenny.rosen@example.com',
      description: 'Customer for jenny.rosen@example.com',
    });
    

    This returns a Customer object:

    {
      "id": "cus_GBV60HKsE0mb5v",
      "object": "customer",
      "address": null,
      "balance": 0,
      "created": 1574101454,
      "currency": "usd",
      "default_source": null,
      "delinquent": false,
      "description": "Customer for jenny.rosen@example.com",
    See all 46 lines "discount": null, "email": null, "invoice_prefix": "373D533", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null }, "livemode": false, "metadata": {}, "name": null, "phone": null, "preferred_locales": [], "shipping": null, "sources": { "object": "list", "data": [], "has_more": false, "url": "/v1/customers/cus_GBV60HKsE0mb5v/sources" }, "subscriptions": { "object": "list", "data": [], "has_more": false, "url": "/v1/customers/cus_GBV60HKsE0mb5v/subscriptions" }, "tax_exempt": "none", "tax_ids": { "object": "list", "data": [], "has_more": false, "url": "/v1/customers/cus_GBV60HKsE0mb5v/tax_ids" }, "tax_info": null, "tax_info_verification": null }

    After creating the customer, store the id value in your database so you can use it later. For example, the next step uses the customer ID to create an invoice.

    3 Create the invoice Server-side

    Creating invoices using the API requires a customer and at least one invoice item. When you create the invoice, the invoice items are automatically added.

    # Using the customer ID returned in step 2
    
    curl https://api.stripe.com/v1/invoiceitems \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d customer=cus_4fdAW5ftNQow1a \
      -d amount=2500 \
      -d currency=usd \
      -d description="One-time setup fee"
    
    curl https://api.stripe.com/v1/invoices \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc: \
      -d customer=cus_4fdAW5ftNQow1a \
      -d auto_advance=true
    
    # 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'
    
    Stripe::InvoiceItem.create({
      customer: 'cus_4fdAW5ftNQow1a',
      amount: 2500,
      currency: 'usd',
      description: 'One-time setup fee',
    })
    
    invoice = Stripe::Invoice.create({
      customer: 'cus_4fdAW5ftNQow1a',
      auto_advance: true, # auto-finalize this draft after ~1 hour
    })
    
    # 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'
    
    stripe.InvoiceItem.create(
      customer='cus_4fdAW5ftNQow1a',
      amount=2500,
      currency='usd',
      description='One-time setup fee'
    )
    
    stripe.Invoice.create(
      customer='cus_4fdAW5ftNQow1a',
      auto_advance=True # auto-finalize this draft after ~1 hour
    )
    
    // 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');
    
    \Stripe\InvoiceItem::create([
        'customer' => 'cus_4fdAW5ftNQow1a',
        'amount' => 2500,
        'currency' => 'usd',
        'description' => 'One-time setup fee',
    ]);
    
    \Stripe\Invoice::create([
        'customer' => 'cus_4fdAW5ftNQow1a',
        'auto_advance' => true, /* auto-finalize this draft after ~1 hour */
    ]);
    
    // 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> invoiceItemParams = new HashMap<String, Object>();
    invoiceItemParams.put("customer", "cus_4fdAW5ftNQow1a");
    invoiceItemParams.put("amount", 2500);
    invoiceItemParams.put("currency", "usd");
    invoiceItemParams.put("description", "One-time setup fee");
    
    InvoiceItem.create(invoiceItemParams);
    
    Map<String, Object> invoiceParams = new HashMap<String, Object>();
    invoiceParams.put("customer", "cus_4fdAW5ftNQow1a");
    invoiceParams.put("auto_advance", true); // auto-finalize this draft after ~1 hour
    
    Invoice.create(invoiceParams);
    
    // 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
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    stripe.invoiceItems.create({
      customer: 'cus_4fdAW5ftNQow1a',
      amount: 2500,
      currency: 'usd',
      description: 'One-time setup fee',
    }, function(err, invoiceItem) {
      // asynchronously called
      stripe.invoices.create({
        customer: 'cus_4fdAW5ftNQow1a',
        auto_advance: true, // auto-finalize this draft after ~1 hour
      }, function(err, invoice) {
        // asynchronously called
      });
    });
    

    To simplify the example, auto_advance is set to true. This means Stripe automatically finalizes the invoice after a few hours, making the invoice ready for payment. In test mode, emails are not sent but you can verify the invoice was created by checking the Invoices section of the Dashboard. The invoice will have a Scheduled status until it’s automatically finalized.

    If you set auto_advance to false, you can continue to modify the invoice until you finalize it. You can finalize a draft invoice using the Dashboard by sending it to the customer or paying it. You can also use the finalize API:

    curl https://api.stripe.com/v1/invoices/:id/finalize \
      -u sk_test_4eC39HqLyjWDarjtT1zdp7dc:
    
    # 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'
    
    invoice = Stripe::Invoice.finalize_invoice('in_18jwqyLlRB0eXbMtrUQ97YBw')
    
    # 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'
    
    invoice = stripe.Invoice.finalize_invoice('in_18jwqyLlRB0eXbMtrUQ97YBw')
    
    // 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');
    
    $invoice = \Stripe\Invoice::retrieve('in_18jwqyLlRB0eXbMtrUQ97YBw');
    $invoice->finalizeInvoice();
    
    // 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";
    
    Invoice invoice = Invoice.retrieve("in_18jwqyLlRB0eXbMtrUQ97YBw");
    invoice.finalizeInvoice();
    
    // 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
    const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');
    
    stripe.invoices.finalizeInvoice('in_18jwqyLlRB0eXbMtrUQ97YBw', function(err, invoice) {
      // asynchronously called
    });
    

    Overview

    This guide describes how to create an invoice and collect payment. Invoices provide an itemized list of goods and services rendered, which includes the cost, quantity, and taxes. You can also use them as a tool to collect payment.

    Businesses that aren’t subscription based but still need to send invoices to their customers commonly use one-off invoices. For example, a consulting business might send invoices for the time and resources that each consultation uses.

    The Stripe Dashboard is the most common way to create one-off invoices. You can automate this process if you integrate with the API. Click the tab below for the flow you want to follow.

    1 Create a customer Dashboard

    The Customer object represents the customer purchasing your product and is required for creating an invoice. One-off invoices are often created using the Stripe Dashboard, but you can automate the process if you integrate with the API.

    To create a customer in the Stripe Dashboard:

    1. Navigate to the Customers page and click the + Add a customer button.
    2. Enter a name, email, and description for the customer.
    3. Click the Create customer button.

    2 Create the invoice Dashboard

    To create an invoice in the Stripe Dashboard:

    1. Navigate to the Invoices page and click the + Create an invoice button.
    2. Click the Select a customer to add the customer you created.
    3. Enter a Description.
    4. Enter a Unit price.
    5. Click Send invoice.
    6. Enter an email address for the customer. This is autofilled using the customer’s email but you can modify it if you want to use a test email address.

    Creating an invoice with the Dashboard.

    Optional Changing payment settings

    Collecting payments for one-off invoices is commonly done by sending an email to customers. The emails include a link to a payment page hosted by Stripe where customers can enter their payment details. You can also collect payment automatically but that requires collecting payment information from customers.

    Default payment settings.

    When using the API, collection_method is automatically set to charge_automatically. This means Stripe automatically charges the customer’s payment method on file. If the charge fails, Stripe automatically retries the payment.

    Alternatively, you can set collection_method to send_invoice. This sends an email to the customer so they can initiate payment. You can build your own payment page and include a link to it in the email or you can use a Stripe-hosted page that allow customers to pay, download, and view the status of their invoice. When you use send_invoice you also have to specify days_until_due or due_date.

    Optional Customizing invoices

    There are several ways to customize invoices. These options allow you to add your own branding and to modify your invoices so that they comply in the jursidictions that you operate it in.

    See also

    Congratulations! You’ve created an invoice on Stripe. Next, you might want to learn more about the invoicing workflow or how to add taxes.

    Was this page helpful?

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    On this page