Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
Invoicing
    Overview
    How Invoicing works
    API quickstart
    Integrate with the API
    Invoicing without code
    Invoice lifecycle
    Preview invoices
    Edit invoices
    Schedule invoice finalization
    Status transitions and finalization
    Send customer emails
    Generate credit notes
    Invoice customers
    Customers
    Customer credit balance
    Customer tax IDs
    Invoice payments
    Hosted Invoice Page
    Create invoice payment plans
    Accept partial payments
    Payment methods for invoices
    Automated collections
    Invoice customization
    Customize invoices
    Invoice rendering templates
    Group invoice line items
    Summarize line items
    Global invoicing
    Best practices
    Multi-currency customers
    Other invoicing features
    Products and prices
    Manage bulk invoice line items
    Taxes
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueInvoicing

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 WINTERSALE promo code for 15% off, run the following API call:

Command Line
cURL
curl https://api.stripe.com/v1/invoices/create_preview \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "invoice_items[0][price]"=price_item_1 \ -d "invoice_items[0][quantity]"=1 \ -d "invoice_items[1][price]"=price_item_3 \ -d "invoice_items[1][quantity]"=1 \ -d "discounts[0][promotion_code]"=promo_WINTERSALE

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
cURL
curl https://api.stripe.com/v1/invoices/upcoming_in_1OujwkClCIKljWvsq5v2ICAN \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

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]:

Command Line
cURL
curl https://api.stripe.com/v1/invoices/create_preview \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "customer_details[address][line1]"="920 5th Ave" \ -d "customer_details[address][city]"=Seattle \ -d "customer_details[address][state]"=WA \ -d "customer_details[address][postal_code]"=98104 \ -d "customer_details[address][country]"=US \ -d "automatic_tax[enabled]"=true \ -d "invoice_items[0][price]"=price_item_1 \ -d "invoice_items[0][quantity]"=1 \ -d "invoice_items[1][price]"=price_item_3 \ -d "invoice_items[1][quantity]"=1 \ -d "discounts[0][promotion_code]"=promo_WINTERSALE

Preview invoices with subscriptions

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

Command Line
cURL
curl https://api.stripe.com/v1/invoices/create_preview \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d "subscription_details[items][0][price]"=price_recurring_4 \ -d "subscription_details[items][0][quantity]"=1 \ -d "invoice_items[0][price]"=price_item_1 \ -d "invoice_items[0][quantity]"=1 \ -d "invoice_items[1][price]"=price_item_3 \ -d "invoice_items[1][quantity]"=1 \ -d "discounts[0][promotion_code]"=promo_WINTERSALE

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 WINTERSALE 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
cURL
curl https://api.stripe.com/v1/invoices/create_preview \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
\ -d preview_mode=recurring \ -d "subscription_details[items][0][price]"=price_recurring_4 \ -d "subscription_details[items][0][quantity]"=1 \ -d "invoice_items[0][price]"=price_item_1 \ -d "invoice_items[0][quantity]"=1 \ -d "invoice_items[1][price]"=price_item_3 \ -d "invoice_items[1][quantity]"=1 \ -d "discounts[0][promotion_code]"=promo_WINTERSALE

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
cURL
curl https://api.stripe.com/v1/invoices/upcoming_in_1OujwkClCIKljWvsq5v2ICAN/lines \ -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc