Preview an invoice

Learn how to create a preview of an invoice.

You can create a preview of an invoice for your customer while they’re considering a purchase. Create a preview to calculate the total invoice amount, retrieve each invoice line, and include any relevant taxes or discounts. Creating a preview allows you to show the total payment amount to your customer without the need to create an invoice.

For example, if you operate a company that provides repair services to businesses, you might present your customers with multiple items that each have different prices and billing schedules:

Item 1: 299 USD one-time service fee
Item 2: 29 USD repair material A
Item 3: 99 USD repair material B
Item 4: 49 USD per month support plan

Customers might want to know how much different combinations of your goods and services cost. If they intend to purchase items 1 and 3 while applying the the related setting promo code for 15% off, run the following API call:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Stripe returns an invoice preview with each of the lines, with the discount applied, and the total amount:

{
 "id": "upcoming_in_1OujwkClCIKljWvsq5v2ICAN",
 "object": "invoice",
 "account_country": "US",
 "account_name": "Stripe Docs",
 "account_tax_ids": null,
 "amount_due": 39800,
 "amount_paid": 0,
 "amount_remaining": 39800,
 "amount_shipping": 0,

Additionally, the resulting invoice preview can be retrieved through the /v1/invoices/:id endpoint for the following 72 hours:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Include Stripe Tax

To preview tax amounts from Stripe Tax, set automatic_tax[enabled] = true and pass the customer’s address in customer_details[address].

Alternatively, you can pass in an IP address in customer_details[tax][ip_address] instead if you don’t have the customer’s address. In most cases, Stripe can resolve an IP address to a physical area, but its precision varies and might not reflect your customer’s actual location. We don’t recommend relying on a customer’s IP address to determine their address beyond an initial estimate.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Preview invoices with subscriptions

To preview the first invoice with a recurring price, use the subscription_details.items parameter:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

To preview changes to an existing subscription, provide the subscription or subscription schedule ID.

Preview the recurring charges only

Your customer might want a recurring subscription along with one-time items, or temporary credits or discounts to use with their purchase. If they want to know what the recurring charges are after any adjustments, use the preview_mode parameter to offer them a preview of the total.

For example, if the related setting is a one-time 15% discount and the customer wants to purchase items 1, 3, and 4, you can retrieve the recurring charge amount with this API call:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

The resulting invoice only contains the 49 USD per month support plan with no discounts. Similarly, you can combine preview_mode with subscription or subscription_schedule to display the expected recurring charge, excluding one-off items and discounts.

Invoice Line pagination

For invoices with more than 10 lines, you can retrieve a paginated view of the lines:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results