Glossary
Stripe Preview Invoice
A Stripe preview invoice is a calculated, not-yet-created invoice that the create preview endpoint returns to show what a customer’s next invoice would contain, including renewals, pending invoice items, discounts, credit balance and any prorations from a change you are considering.
Also called: upcoming invoice, create_preview, invoice.upcoming
14-day free trial · card required · cancel anytime
Definition
A preview invoice answers one question: if Stripe billed this customer next, what would the invoice say? You ask by calling the create preview endpoint, optionally passing the subscription change you are thinking about, and Stripe returns a full invoice object built from the current state plus your hypothetical.
The important word is preview. Stripe’s API reference is explicit that “the invoice has not yet been created. As such, the upcoming invoice will not show up in invoice listing calls, and you cannot use the API to pay or edit the invoice.” It has an ID, but that ID starts with upcoming_in and points at nothing you can retrieve later.
That makes it the safest tool Stripe offers for month-end questions. You can see what next month’s renewal run will bill, or what a seat change will cost, before anything is created that your books would have to account for.
Key points
- +Created with the create preview endpoint (POST /v1/invoices/create_preview). Stripe’s reference calls the result the upcoming invoice, and the word survives in the invoice.upcoming event and the upcoming billing_reason.
- +Shows all pending charges for the next invoice: subscription renewal charges, pending invoice items, discounts and any existing customer credit balance.
- +Can model a change before you make it: a different price, a new quantity, a trial, a coupon, or a whole new subscription.
- +Never becomes a real invoice. It is not listed, cannot be paid or edited, and its ID is prefixed with upcoming_in.
- +Its billing_reason is upcoming, a value Stripe reserves for previews and for invoice.upcoming events.
- +To lock a previewed proration, pass subscription_details.proration_date on the preview and the same proration_date on the real update.
- +preview_mode set to recurring returns a long-term estimate with only recurring items, taxes and repeating or forever coupons.
- +invoice.upcoming is the related webhook, sent a few days before a renewal for subscriptions that charge automatically.
What goes into a preview
Stripe’s subscription invoices guide lists the inputs: the preview “reflects the base price, pending invoice items, discounts, and any existing customer credit balance.” In other words, everything Stripe would sweep onto the next invoice if it were finalized now.
Which invoice you get depends on what you pass. Name a subscription and you get that subscription’s next invoice. Pass subscription_details.items without a subscription and Stripe previews creating a new subscription with those items. Pass neither and Stripe returns “the next upcoming invoice from among the customer’s subscriptions.” A schedule can be previewed the same way with schedule and schedule_details, but not in the same call as the subscription fields.
Two inputs are easy to forget. Exchange rates are the latest ones, and Stripe warns they “may vary between the time of the preview and the time of the actual invoice creation.” And discounts are inherited from the subscription or customer unless you override them, so a preview passed an empty discounts value shows the price without the coupon.
Previewing a change before you make it
The most common use is pricing a subscription change. Stripe’s subscription invoices guide names four you can model: swapping the underlying price, altering the quantity, applying a trial period and adding a coupon. The create preview reference adds that it includes “a preview of any prorations that will take place.”
To pull out just the proration lines, Stripe recommends filtering on line items where parent.subscription_item_details.proration is true. A seat increase usually shows two of them: a credit for unused time at the old quantity and a debit for the remaining time at the new one.
The catch is timing. Stripe prorates to the second, so the number can move between the preview and the update. Stripe’s fix is to pass subscription_details.proration_date when you create the preview, then pass the same timestamp as proration_date when you update the subscription, so the real proration is calculated at exactly the previewed moment.
next versus recurring
The preview_mode parameter changes what the preview is estimating. The default, next, calculates the next invoice “factoring in all one-time and recurring items”: renewals, pending items, prorations and one-off charges together.
Setting it to recurring calculates “an estimate of the subscription’s long-term recurring bill.” Only recurring subscription items, taxes and coupons with duration repeating or forever are included. Stripe notes that “Prorations, subscription cancellations, trials, and pauses are not supported with recurring estimates.”
The difference matters if you use previews for forecasting. A next preview for a customer who just added seats is inflated by a one-time proration. A recurring preview shows the run rate you should actually expect from that customer each month.
invoice.upcoming and the renewal warning
Stripe also produces previews on its own. The invoice.upcoming webhook is “sent a few days prior to the renewal of the subscription,” with the lead time set by Upcoming renewal events in the Dashboard’s billing automatic settings. Changing that number takes effect from the next billing period.
The event exists so you can act before the invoice is drafted, for example by adding extra invoice items to the coming renewal. Stripe documents one gap: if collection_method is send_invoice, Stripe doesn’t send an invoice.upcoming event.
Either way, the object in the event is still a preview. It carries billing_reason upcoming, which is the value to exclude whenever you sum invoices, because previews are not bills.
Why a preview is useful at month-end
Because a preview is never created, it is the one invoice object you can generate freely without leaving anything behind in Stripe or in your accounting system. That makes it a clean way to answer the questions a bookkeeper gets asked near a renewal date.
What will this customer be charged on the first? Preview the subscription. Will the seats they added last week bill now or at renewal? Preview it, and look for proration lines. Is a credit balance going to reduce the next invoice? The preview includes any existing customer credit balance.
What a preview cannot tell you is what was actually billed. For that you need the finalized invoice, and the totals can differ if usage, exchange rates or pending items change between the preview and the moment Stripe finalizes.
Why a preview never reaches QuickBooks with Acodei
Acodei’s Invoice Sync, a paid-plan feature, creates a QuickBooks invoice from a Stripe invoice when it is finalized, and creates and applies the payment when the Stripe invoice is paid. The Stripe events its documentation lists for invoices are invoice.created and invoice.finalized, invoice.paid or charge.succeeded, invoice.voided, invoice.marked_uncollectible and credit_note.created. invoice.upcoming is not among them.
A preview is never finalized, never paid and never created, so there is nothing for QuickBooks to receive. The QuickBooks invoice appears when Stripe finalizes the real invoice, and its lines are reproduced as your mapping settings allow, which may differ from the preview if anything changed in between.
Want to see this on your own Stripe data?
Start a free trial14-day free trial · card required · cancel anytime
Frequently asked questions
What is a preview invoice in Stripe?
It is an invoice object Stripe calculates on request to show what a customer’s next invoice would contain. It includes renewal charges, pending invoice items, discounts, any existing customer credit balance and any prorations from a change you pass in. It is not a real invoice: it is not listed, cannot be paid or edited, and its ID starts with upcoming_in.
Is the upcoming invoice the same as a preview invoice?
Yes. The endpoint is called create preview, and Stripe’s reference describes what it returns as the upcoming invoice: “when you are viewing an upcoming invoice, you are simply viewing a preview.” The same word appears in the invoice.upcoming webhook sent before renewals and in the billing_reason value upcoming, which Stripe reserves for invoices created through the Create Preview Invoice API or generated for an invoice.upcoming event.
How do I preview a proration before changing a subscription?
Call create preview with the subscription and the change in subscription_details, such as a new quantity or price. Filter the returned lines for parent.subscription_item_details.proration set to true. Pass subscription_details.proration_date on the preview and the same proration_date on the actual update so the real proration matches the preview to the second.
Why doesn’t the final invoice match the preview?
Something changed between the two. Common causes are a proration calculated at a different second, new pending invoice items, metered usage that arrived after the preview, and exchange rates, which Stripe says may vary between the preview and the actual invoice creation.
Does a Stripe preview invoice show up in QuickBooks?
No. A preview is never created, finalized or paid. With Acodei’s Invoice Sync, a QuickBooks invoice is created when the real Stripe invoice is finalized, and the payment is applied when that invoice is paid.
What customers say about running Stripe through Acodei
“If you're testing out all the different Stripe/QuickBooks integration apps right now, let me save you some time. This one is the best one by far.”
“Works well and is really helpful for massive transactions. The support is really fast and helpful. 100% recommended.”
Related reading
- Stripe Proration
- Stripe Invoice Item
- Stripe Pending Update
- Stripe Subscription Item
- Stripe Webhook
- Stripe billing_reason values
More glossary terms
- Undeposited Funds
- Stripe Balance Transaction
- Available vs Pending Balance
- Stripe Dispute
- Stripe Dispute Evidence
- Stripe Fee
- Stripe Balance Adjustment
- QuickBooks Credit Memo
- Stripe Tax
- QuickBooks Tax Code
- Stripe Reserve
- Stripe Tax Rate
- Stripe Fee Credit
- Stripe Credit Note
- QuickBooks Product/Service Item
- Stripe Payout
- QuickBooks Sales Receipt
- QuickBooks Bank Deposit
- QuickBooks Transfer
- Stripe Authorization Hold
- QuickBooks Refund Receipt
- QuickBooks Payment
- QuickBooks Expense
- QuickBooks Journal Entry
- Stripe Financial Account
- Holding Account
- Accounts Receivable
- Bank Feed
- Deferred Revenue
- Stripe PaymentIntent
- Stripe Checkout Session
- Stripe SetupIntent
- Stripe PaymentMethod
- Stripe Charge
- Stripe Refund
- QuickBooks Invoice
- QuickBooks Class Tracking
- QuickBooks Location Tracking
- QuickBooks Project
- QuickBooks Closing Date
- Stripe Invoice Line Item
- Stripe Proration
- Stripe Invoice Status
- Stripe Shipping Rate
- Stripe Transfer
- Stripe Mandate
- Stripe on_behalf_of
- Stripe Invoice Item
- QuickBooks Estimate
- Stripe Invoice Payment
- Stripe Invoice Payment Settings
- Stripe Billing Meter
- Stripe Invoice Template
- Stripe Price
- Stripe Subscription Schedule
- Stripe Subscription Item
- QuickBooks Recurring Transaction
- QuickBooks Sub-Customer
- QuickBooks Audit Log
- QuickBooks Bank Rule
- Stripe Subscription Status
- Stripe Mixed Interval Subscription
- Stripe Trial Settings
- QuickBooks Payment Terms
- Stripe Pending Update
- QuickBooks Tags
- QuickBooks Credit Card Credit
- QuickBooks Vendor Credit
- QuickBooks Bill
- QuickBooks Delayed Charge
- Stripe Billing Mode
- QuickBooks Billable Expense
- Stripe Customer Cash Balance
- QuickBooks Purchase Order
- QuickBooks Opening Balance
- QuickBooks Account Type
- QuickBooks Sales Tax Center
- Stripe Webhook
- Stripe Metadata
- Stripe Outbound Payment
- Stripe Received Credit
- Stripe Outbound Transfer
- Stripe Inbound Transfer
- Stripe Received Debit
- Stripe Payout Method
- Stripe Financial Account Transaction
- Stripe Financial Address
- Stripe Application Fee
- Stripe Connected Account
- Stripe Destination Charge
- Stripe Separate Charges and Transfers
- Stripe Direct Charge
- Stripe Payment Method Configuration
- Stripe Dynamic Payment Methods
- Stripe Payment Method Rules
- QuickBooks Bundle
- Stripe Account Capability
- Stripe Merchant of Record
- Stripe Data Pipeline
- Settlement Currency
- Hosted Invoice Page
- Stripe Customer
- Stripe Product
- QuickBooks Home Currency
- QuickBooks Exchange Gain or Loss
- QuickBooks Trial Balance
- QuickBooks General Ledger Report
- QuickBooks Retained Earnings
- QuickBooks Profit and Loss Report
- QuickBooks Balance Sheet Report
- QuickBooks Account Register
- QuickBooks Reclassify Transactions
- QuickBooks A/R Aging Report
- QuickBooks Sales Tax Liability Report
- QuickBooks Sales Tax Payable
- Stripe Tax Transaction
- Stripe Tax Location Report
- Stripe Tax Summarized Export
- Stripe Tax Itemized Export
- Stripe Product Tax Code
- QuickBooks Vendor
- Economic Nexus
- Reverse Charge
- Stripe Statement Descriptor
- Stripe Taxability Reason
- Stripe Tax Filing Currency
- Stripe Tax Cross-Border Goods Option
- Stripe Tax Threshold Monitoring
- QuickBooks Uncategorized Income
- QuickBooks Sales by Product/Service Report
- QuickBooks Sales by Customer Report
- QuickBooks Group Tax Rate
- Form 1099-NEC
- SEPA Direct Debit
- Bacs Direct Debit
- Canadian Pre-Authorized Debit (PAD)
- Australia BECS Direct Debit
- Stripe PayTo
- Stripe Test Clock
- QuickBooks Customer Display Name
- Backup Withholding
- QuickBooks Multicurrency
- Form 1042-S
- Form W-8BEN
- Form W-9
- Form 8233
- Form 1042
- Form 1099-K
- Form W-8BEN-E
- Stripe Tax Behavior
- Stripe Customer Tax ID
- Form 945
- ITIN (Individual Taxpayer Identification Number)
- Form 1099-MISC
- Stripe Customer Tax Exempt Status
- EFTPS (Electronic Federal Tax Payment System)
- Tax Representative (Fiscal Representative)
- Nil Return
- Sales Tax Exemption Certificate
- EU One Stop Shop (OSS)
- Place of Supply
- Simplified Tax Invoice
- Input VAT (Input Tax)
- Streamlined Sales Tax (SST)
- Fixed Establishment (VAT)
- VIES VAT Number Validation
- E-Invoicing Mandate
- Tax Point (Time of Supply)
- Sales Tax Holiday
- Digital Services Tax
- VAT Invoice (Full Tax Invoice)
- Output VAT (Output Tax)
- VAT Bad Debt Relief
- Sales Tax Sourcing
- Gross Receipts Tax
- VAT Cash Accounting Scheme
- Reduced VAT Rate
- VAT Flat Rate Scheme (UK)
- VAT Annual Accounting Scheme (UK)
- EU VAT SME Scheme
- Making Tax Digital for VAT
- VAT Payments on Account (UK)
- Stripe Tax Registration
- Non-Established Taxable Person (NETP)
- VAT Group Registration (UK)
- Zero-Rated vs Exempt Supply
- Electronically Supplied Services (ESS)
- Zero-Decimal Currency
- UK VAT Registration Threshold
- QuickBooks Deposit Detail Report
- Payment Settlement Entity (PSE)
- QuickBooks Reconcile
- QuickBooks Bad Debt Write-Off
- Stripe Radar
- Stripe Smart Retries
- Stripe Decline Code
- QuickBooks Voided Transaction
- Stripe Minimum Charge Amount
- Stripe 3D Secure
Ready to try Acodei?
Connect Stripe to QuickBooks Online in minutes and let the fees, refunds, and payouts land where your accountant expects them.
14-day free trial · card required · cancel anytime