Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
Overview
Billing
OverviewAbout the Billing APIs
Tax
Overview
Reporting
OverviewReports for multiple accounts
Data
OverviewSchema

Integrate with the Invoicing API

Learn how to create and send an invoice with code.

The Dashboard is the most common way to create invoices. If you’d like to automate invoice creation, you can integrate with the API. Build a full, working Invoicing integration using our sample integration.

Note

You don’t need to integrate with the Payments API to integrate with the Invoicing API.

Set up Stripe

Use our official libraries for access to the Stripe API:

Command Line
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a product

To create a product, enter its name:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/products \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Gold Special"

Create a price

Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the billing interval (when the price is for a subscription). Like products, if you only have a few prices, it’s preferable to manage them in the Dashboard. Use the unit amount to express prices in the lowest unit of the currency—in this case, cents (10 USD is 1,000 cents, so the unit amount is 1000).

Note

As an alternative, if you don’t need to create a price for your product, you can use the amount parameter during invoice item creation.

To create a price and assign it to the product, pass the product ID, unit amount, and currency. In the following example, the price for the “Gold Special” product is 10 USD:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/prices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d product=
{{PRODUCT_ID}}
 \
  -d unit_amount=1000 \
  -d currency=usd

Create a customer

The Customer object represents the customer purchasing your product. It’s required for creating an invoice. To create a customer with a name, email, and description, add the following code replacing the values with your own:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="Jenny Rosen" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d description="My first customer"

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

Note

See Create a customer for additional parameters.

Create an invoice

Set the collection_method attribute to send_invoice. For Stripe to mark an invoice as past due, you must add the days_until_due parameter. When you send an invoice, Stripe emails the invoice to the customer with payment instructions.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d collection_method=send_invoice \
  -d days_until_due=30

Then, create an invoice item by passing in the customer id, product price, and invoice ID invoice.

The maximum number of invoice items is 250.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoiceitems \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "pricing[price]"=
{{PRICE_ID}}
 \
  -d invoice=
{{INVOICE_ID}}

If you set auto_advance to false, you can continue to modify the invoice until you finalize it. To finalize a draft invoice, use the Dashboard, send it to the customer, or pay it. You can also use the Finalize API:

Note

If you created the invoice in error, void it. You can also mark an invoice as uncollectible.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
/finalize \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Accept invoice payment

Send the invoice to the email address associated with the customer. Stripe finalizes the invoice as soon as you send it. Many jurisdictions consider finalized invoices a legal document making certain fields unalterable. If you send invoices that have already been paid, there’s no reference to the payment in the email.

Note

When you send invoices that have already been paid, the email doesn’t reference the payment. Stripe sends invoices to the email address associated with the customer.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/invoices/
{{INVOICE_ID}}
/send \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Handle post-payment events

Stripe sends an invoice.paid event when an invoice payment completes. Listen for this event to ensure reliable fulfillment. If your integration relies on only a client-side callback, the customer could lose connection before the callback executes, which would result in the customer being charged without your server being notified. Setting up your integration to listen for asynchronous events is also what enables you to accept different types of payment methods with a single integration.

Note

Successful invoice payments trigger both an invoice.paid and invoice.payment_succeeded event. Both event types contain the same invoice data, so it’s only necessary to listen to one of them to be notified of successful invoice payments. The difference is that invoice.payment_succeeded events are sent for successful invoice payments, but aren’t sent when you mark an invoice as paid_out_of_band. invoice.paid events, on the other hand, are triggered for both successful payments and out of band payments. Because invoice.paid covers both scenarios, we typically recommend listening to invoice.paid rather than invoice.payment_succeeded.

Use the Dashboard webhook tool or follow the webhook quickstart to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

In addition to handling the invoice.paid event, we recommend handling two other events when collecting payments with the Payment Element:

EventDescriptionAction
payment_intent.processingSent when a customer successfully initiated a payment, but the payment has yet to complete. This event is most commonly sent when a bank debit is initiated. It’s followed by either a invoice.paid or invoice.payment_failed event in the future.Send the customer an order confirmation that indicates their payment is pending. For digital goods, you might want to fulfill the order before waiting for payment to complete.
invoice.payment_failedSent when a customer attempted a payment on an invoice, but the payment failed.If a payment transitioned from processing to payment_failed, offer the customer another attempt to pay.

OptionalCustomize an invoice

You can customize invoices in several ways. Stripe’s customization options allow you to add your own branding and to modify your invoices so that they comply in the jurisdictions ​​where you operate.

Custom fields

Add custom fields to enhance your invoice PDF documents and help you comply with your business practice and tax reporting obligations. Custom fields allow you to provide up to four key-value pairs ​​that display in the invoice header. You can set up to four custom field key-value pairs in the Invoice Editor, with the Invoices API, or with Invoice Templates.

Some common uses for custom fields are:

  • Purchase Order (PO) numbers
  • Contractor numbers
  • Tax compliance

Here’s an example of creating an invoice with a PO Number and value-added tax (VAT) as custom fields:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/invoices \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "custom_fields[0][name]"="PO number" \
  -d "custom_fields[0][value]"=12345 \
  -d "custom_fields[1][name]"=VAT \
  -d "custom_fields[1][value]"=123ABC

Custom field inheritance

You can set custom invoice fields on the Customer object. Any custom fields you set at the customer level apply to all of the draft invoices you generate for that customer. You can always modify these inherited custom fields while the invoice is still a draft. After the invoice finalizes, you can’t update the custom fields.

Here’s an example of adding custom fields at the customer level to apply to all future generated draft invoices:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode email="jenny.rosen@example.com" \
  -d payment_method=pm_card_visa \
  -d "invoice_settings[default_payment_method]"=pm_card_visa \
  -d "invoice_settings[custom_fields][0][name]"="PO number" \
  -d "invoice_settings[custom_fields][0][value]"=12345 \
  -d "invoice_settings[custom_fields][1][name]"=VAT \
  -d "invoice_settings[custom_fields][1][value]"=123ABC

See also

Was this page helpful?
YesNo
Code quickstart
Related Guides
How Invoicing Works
Invoicing API
Hosted Invoice Page