Retrieve an upcoming invoice

Billing

Invoices

At any time, you can preview the upcoming invoice for a customer. This will show you all the charges that are pending, including subscription renewal charges, invoice item charges, etc. It will also show you any discounts that are applicable to the invoice.

Note that when you are viewing an upcoming invoice, you are simply viewing a preview – 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. If you want to change the amount that your customer will be billed, you can add, remove, or update pending invoice items, or update the customer’s discount.

You can preview the effects of updating a subscription, including a preview of what proration will take place. To ensure that the actual proration is calculated exactly the same as the previewed proration, you should pass the subscription_details.proration_date parameter when doing the actual subscription update. The recommended way to get only the prorations being previewed is to consider only proration line items where period[start] is equal to the subscription_details.proration_date value passed in the request.

Note: Currency conversion calculations use the latest exchange rates. Exchange rates may vary between the time of the preview and the time of the actual invoice creation. Learn more

Parameters

automatic_taxobject

Settings for automatic tax lookup for this invoice preview.

automatic_tax.enabledbooleanRequired
Whether Stripe automatically computes tax on this invoice. Note that incompatible invoice items (invoice items with manually specified tax rates, negative amounts, or tax_behavior=unspecified) cannot be added to automatic tax invoices.

automatic_tax.liabilityobjectConnect only

The account that’s liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.

automatic_tax.liability.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

automatic_tax.liability.accountstringRequired only if type is account
The connected account being referenced when type is account.

customerstring
The identifier of the customer whose upcoming invoice you’d like to retrieve. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.

subscriptionstring
The identifier of the subscription for which you’d like to retrieve the upcoming invoice. If not provided, but a subscription_details.items is provided, you will preview creating a subscription with those items. If neither subscription nor subscription_details.items is provided, you will retrieve the next upcoming invoice from among the customer’s subscriptions.

More parameters

couponstringDeprecated
The ID of the coupon to apply to this invoice. This field has been deprecated and will be removed in a future API version. Use discounts instead.

currencyenum
The currency to preview this invoice in. Defaults to that of customer if not specified.

customer_detailsobject
Details about the customer you want to invoice or overrides for an existing customer. If automatic_tax is enabled then one of customer, customer_details, subscription, or schedule must be set.
- customer_details.addressobjectRequired if calculating taxes
  The customer’s address.
  customer_details.address.citystring
  City, district, suburb, town, or village.
  customer_details.address.countrystringRequired for calculating taxes
  Two-letter country code (ISO 3166-1 alpha-2).
  customer_details.address.line1string
  Address line 1 (e.g., street, PO Box, or company name).
  customer_details.address.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
  customer_details.address.postal_codestringRequired for calculating taxes
  ZIP or postal code.
  customer_details.address.statestring
  State, county, province, or region.
- customer_details.shippingobject
  The customer’s shipping information. Appears on invoices emailed to this customer.
  customer_details.shipping.addressobjectRequired
  Customer shipping address.
  customer_details.shipping.address.citystring
  City, district, suburb, town, or village.
  customer_details.shipping.address.countrystringRequired if calculating taxes
  A freeform text field for the country. However, in order to activate some tax features, the format should be a two-letter country code (ISO 3166-1 alpha-2).
  customer_details.shipping.address.line1string
  Address line 1 (e.g., street, PO Box, or company name).
  customer_details.shipping.address.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
  customer_details.shipping.address.postal_codestringRequired if calculating taxes
  ZIP or postal code.
  customer_details.shipping.address.statestring
  State, county, province, or region.
  customer_details.shipping.namestringRequired
  Customer name.
  customer_details.shipping.phonestring
  Customer phone (including extension).
- customer_details.taxobject
  Tax details about the customer.
  customer_details.tax.ip_addressstring
  A recent IP address of the customer used for tax reporting and tax location inference. Stripe recommends updating the IP address when a new PaymentMethod is attached or the address field on the customer is updated. We recommend against updating this field more frequently since it could result in unexpected tax location/reporting outcomes.
- customer_details.tax_exemptenum
  The customer’s tax exemption. One of none, exempt, or reverse.
  Possible enum values
  exempt
  none
  reverse
- customer_details.tax_idsarray of objects
  The customer’s tax IDs.
  customer_details.tax_ids.typestringRequired
  Type of the tax ID, one of ad_nrt, ae_trn, ar_cuit, au_abn, au_arn, bg_uic, bh_vat, bo_tin, br_cnpj, br_cpf, by_tin, ca_bn, ca_gst_hst, ca_pst_bc, ca_pst_mb, ca_pst_sk, ca_qst, ch_uid, ch_vat, cl_tin, cn_tin, co_nit, cr_tin, de_stn, do_rcn, ec_ruc, eg_tin, es_cif, eu_oss_vat, eu_vat, gb_vat, ge_vat, hk_br, hr_oib, hu_tin, id_npwp, il_vat, in_gst, is_vat, jp_cn, jp_rn, jp_trn, ke_pin, kr_brn, kz_bin, li_uid, li_vat, ma_vat, md_vat, mx_rfc, my_frp, my_itn, my_sst, ng_tin, no_vat, no_voec, nz_gst, om_vat, pe_ruc, ph_tin, ro_tin, rs_pib, ru_inn, ru_kpp, sa_vat, sg_gst, sg_uen, si_tin, sv_nit, th_vat, tr_tin, tw_vat, tz_vat, ua_vat, us_ein, uy_ruc, uz_tin, uz_vat, ve_rif, vn_tin, or za_vat
  customer_details.tax_ids.valuestringRequired
  Value of the tax ID.

discountsarray of objects
The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the subscription or customer. This works for both coupons directly applied to an invoice and coupons applied to a subscription. Pass an empty string to avoid inheriting any discounts.
- discounts.couponstring
  ID of the coupon to create a new discount for.
- discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
- discounts.promotion_codestring
  ID of the promotion code to create a new discount for.

invoice_itemsarray of objects
List of invoice items to add or update in the upcoming invoice preview (up to 250).
- invoice_items.amountinteger
  The integer amount in cents of previewed invoice item.
- invoice_items.currencyenum
  Three-letter ISO currency code, in lowercase. Must be a supported currency. Only applicable to new invoice items.
- invoice_items.descriptionstring
  An arbitrary string which you can attach to the invoice item. The description is displayed in the invoice for easy tracking.
- invoice_items.discountableboolean
  Explicitly controls whether discounts apply to this invoice item. Defaults to true, except for negative invoice items.
- invoice_items.discountsarray of objects
  The coupons to redeem into discounts for the invoice item in the preview.
  invoice_items.discounts.couponstring
  ID of the coupon to create a new discount for.
  invoice_items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  invoice_items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- invoice_items.invoiceitemstring
  The ID of the invoice item to update in preview. If not specified, a new invoice item will be added to the preview of the upcoming invoice.
- invoice_items.metadataobject
  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
- invoice_items.periodobject
  The period associated with this invoice item. When set to different values, the period will be rendered on the invoice. If you have Stripe Revenue Recognition enabled, the period will be used to recognize and defer revenue. See the Revenue Recognition documentation for details.
  invoice_items.period.endtimestampRequired
  The end of the period, which must be greater than or equal to the start. This value is inclusive.
  invoice_items.period.starttimestampRequired
  The start of the period. This value is inclusive.
- invoice_items.pricestring
  The ID of the price object. One of price or price_data is required.
- invoice_items.price_dataobject
  Data used to generate a new Price object inline. One of price or price_data is required.
  invoice_items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  invoice_items.price_data.productstringRequired
  The ID of the product that this price will belong to.
  invoice_items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  invoice_items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge.
  invoice_items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- invoice_items.quantityinteger
  Non-negative integer. The quantity of units for the invoice item.
- invoice_items.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
- invoice_items.tax_codestringRecommended if calculating taxes
  A tax code ID.
- invoice_items.tax_ratesarray of strings
  The tax rates that apply to the item. When set, any default_tax_rates do not apply to this item.
- invoice_items.unit_amountinteger
  The integer unit amount in cents of the charge to be applied to the upcoming invoice. This unit_amount will be multiplied by the quantity to get the full amount. If you want to apply a credit to the customer’s account, pass a negative unit_amount.
- invoice_items.unit_amount_decimalstring
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.

issuerobjectConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

on_behalf_ofstringConnect only
The account (if any) for which the funds of the invoice payment are intended. If set, the invoice will be presented with the branding and support information of the specified account. See the Invoices with Connect documentation for details.

preview_modeenum

Customizes the types of values to include when calculating the invoice. Defaults to next if unspecified.

Possible enum values

next

Will calculate the next invoice for the customer or subscription, factoring in all one-time and recurring items.

recurring

Will calculate an invoice that is an estimate of the subscription’s long-term recurring bill. The invoice lines will only include recurring subscription items, taxes, and coupons with duration=repeating or duration=forever.

To calculate a recurring estimate, you must provide at least one of subscription or subscription_details.items. Prorations, subscription cancellations, and trials are not supported with recurring estimates.

schedulestring
The identifier of the schedule whose upcoming invoice you’d like to retrieve. Cannot be used with subscription or subscription fields.

schedule_detailsobject

The schedule creation or modification params to apply as a preview. Cannot be used with subscription or subscription_ prefixed fields.

schedule_details.end_behaviorenum
Behavior of the subscription schedule and underlying subscription when it ends. Possible values are release or cancel with the default being release. release will end the subscription schedule and keep the underlying subscription running. cancel will end the subscription schedule and cancel the underlying subscription.
Possible enum values
cancel
release

schedule_details.phasesarray of objects

List representing phases of the subscription schedule. Each phase can be customized to have different durations, plans, and coupons. If there are multiple phases, the end_date of one phase will always equal the start_date of the next phase.

schedule_details.phases.itemsarray of objectsRequired
List of configuration items, each with an attached price, to apply during this phase of the subscription schedule.
- schedule_details.phases.items.billing_thresholdsobject
  Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
  schedule_details.phases.items.billing_thresholds.usage_gteintegerRequired
  Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 monetary threshold)
- schedule_details.phases.items.discountsarray of objects
  The coupons to redeem into discounts for the subscription item.
  schedule_details.phases.items.discounts.couponstring
  ID of the coupon to create a new discount for.
  schedule_details.phases.items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  schedule_details.phases.items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- schedule_details.phases.items.metadataobject
  Set of key-value pairs that you can attach to a configuration item. Metadata on a configuration item will update the underlying subscription item’s metadata when the phase is entered, adding new keys and replacing existing keys. Individual keys in the subscription item’s metadata can be unset by posting an empty value to them in the configuration item’s metadata. To unset all keys in the subscription item’s metadata, update the subscription item directly or unset every key individually from the configuration item’s metadata.
- schedule_details.phases.items.pricestring
  The ID of the price object.
- schedule_details.phases.items.price_dataobject
  Data used to generate a new Price object inline.
  schedule_details.phases.items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  schedule_details.phases.items.price_data.productstringRequired
  The ID of the product that this price will belong to.
  schedule_details.phases.items.price_data.recurringobjectRequired
  The recurring components of a price such as interval and interval_count.
  schedule_details.phases.items.price_data.recurring.intervalenumRequired
  Specifies billing frequency. Either day, week, month or year.
  Possible enum values
  day
  month
  week
  year
  schedule_details.phases.items.price_data.recurring.interval_countinteger
  The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
  schedule_details.phases.items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  schedule_details.phases.items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge.
  schedule_details.phases.items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- schedule_details.phases.items.quantityinteger
  Quantity for the given price. Can be set only if the price’s usage_type is licensed and not metered.
- schedule_details.phases.items.tax_ratesarray of strings
  A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

schedule_details.phases.add_invoice_itemsarray of objects
A list of prices and quantities that will generate invoice items appended to the next invoice for this phase. You may pass up to 20 items.
- schedule_details.phases.add_invoice_items.discountsarray of objects
  The coupons to redeem into discounts for the item.
  schedule_details.phases.add_invoice_items.discounts.couponstring
  ID of the coupon to create a new discount for.
  schedule_details.phases.add_invoice_items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  schedule_details.phases.add_invoice_items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- schedule_details.phases.add_invoice_items.pricestring
  The ID of the price object. One of price or price_data is required.
- schedule_details.phases.add_invoice_items.price_dataobject
  Data used to generate a new Price object inline. One of price or price_data is required.
  schedule_details.phases.add_invoice_items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  schedule_details.phases.add_invoice_items.price_data.productstringRequired
  The ID of the product that this price will belong to.
  schedule_details.phases.add_invoice_items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  schedule_details.phases.add_invoice_items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge or a negative integer representing the amount to credit to the customer.
  schedule_details.phases.add_invoice_items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- schedule_details.phases.add_invoice_items.quantityinteger
  Quantity for this item. Defaults to 1.
- schedule_details.phases.add_invoice_items.tax_ratesarray of strings
  The tax rates which apply to the item. When set, the default_tax_rates do not apply to this item.

schedule_details.phases.application_fee_percentfloatConnect only
A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner’s Stripe account. The request must be made by a platform account on a connected account in order to set an application fee percentage. For more information, see the application fees documentation.

schedule_details.phases.automatic_taxobject

Automatic tax settings for this phase.

schedule_details.phases.automatic_tax.enabledbooleanRequired
Enabled automatic tax calculation which will automatically compute tax rates on all invoices generated by the subscription.

schedule_details.phases.automatic_tax.liabilityobjectConnect only

schedule_details.phases.automatic_tax.liability.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

schedule_details.phases.automatic_tax.liability.accountstringRequired only if type is account
The connected account being referenced when type is account.

schedule_details.phases.billing_cycle_anchorenum
Can be set to phase_start to set the anchor to the start of the phase or automatic to automatically change it if needed. Cannot be set to phase_start if this phase specifies a trial. For more information, see the billing cycle documentation.
Possible enum values
automatic
phase_start

schedule_details.phases.billing_thresholdsobject
Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. Pass an empty string to remove previously-defined thresholds.
- schedule_details.phases.billing_thresholds.amount_gteinteger
  Monetary threshold that triggers the subscription to advance to a new billing period
- schedule_details.phases.billing_thresholds.reset_billing_cycle_anchorboolean
  Indicates if the billing_cycle_anchor should be reset when a threshold is reached. If true, billing_cycle_anchor will be updated to the date/time the threshold was last reached; otherwise, the value will remain unchanged.

schedule_details.phases.collection_methodenum
Either charge_automatically, or send_invoice. When charging automatically, Stripe will attempt to pay the underlying subscription at the end of each billing cycle using the default source attached to the customer. When sending an invoice, Stripe will email your customer an invoice with payment instructions and mark the subscription as active. Defaults to charge_automatically on creation.
Possible enum values
charge_automatically
send_invoice

schedule_details.phases.couponstringDeprecated
The ID of the coupon to apply to this phase of the subscription schedule. This field has been deprecated and will be removed in a future API version. Use discounts instead.

schedule_details.phases.default_payment_methodstring
ID of the default payment method for the subscription schedule. It must belong to the customer associated with the subscription schedule. If not set, invoices will use the default payment method in the customer’s invoice settings.

schedule_details.phases.default_tax_ratesarray of strings
A list of Tax Rate ids. These Tax Rates will set the Subscription’s default_tax_rates, which means they will be the Invoice’s default_tax_rates for any Invoices issued by the Subscription during this Phase.

schedule_details.phases.descriptionstring
Subscription description, meant to be displayable to the customer. Use this field to optionally store an explanation of the subscription for rendering in Stripe surfaces and certain local payment methods UIs.

schedule_details.phases.discountsarray of objects
The coupons to redeem into discounts for the schedule phase. If not specified, inherits the discount from the subscription’s customer. Pass an empty string to avoid inheriting any discounts.
- schedule_details.phases.discounts.couponstring
  ID of the coupon to create a new discount for.
- schedule_details.phases.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
- schedule_details.phases.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.

schedule_details.phases.end_datetimestamp | string
The date at which this phase of the subscription schedule ends. If set, iterations must not be set.

schedule_details.phases.invoice_settingsobject

All invoices will be billed using the specified settings.

schedule_details.phases.invoice_settings.account_tax_idsarray of strings
The account tax IDs associated with this phase of the subscription schedule. Will be set on invoices generated by this phase of the subscription schedule.

schedule_details.phases.invoice_settings.days_until_dueinteger
Number of days within which a customer must pay invoices generated by this subscription schedule. This value will be null for subscription schedules where billing=charge_automatically.

schedule_details.phases.invoice_settings.issuerobjectConnect only

The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

schedule_details.phases.invoice_settings.issuer.typeenumRequired

Type of the account referenced in the request.

Possible enum values

account

Indicates that the account being referenced is a connected account which is different from the account making the API request but related to it.

self

Indicates that the account being referenced is the account making the API request.

schedule_details.phases.invoice_settings.issuer.accountstringRequired only if type is account
The connected account being referenced when type is account.

schedule_details.phases.iterationsinteger
Integer representing the multiplier applied to the price interval. For example, iterations=2 applied to a price with interval=month and interval_count=3 results in a phase of duration 2 * 3 months = 6 months. If set, end_date must not be set.

schedule_details.phases.metadataobject
Set of key-value pairs that you can attach to a phase. Metadata on a schedule’s phase will update the underlying subscription’s metadata when the phase is entered, adding new keys and replacing existing keys in the subscription’s metadata. Individual keys in the subscription’s metadata can be unset by posting an empty value to them in the phase’s metadata. To unset all keys in the subscription’s metadata, update the subscription directly or unset every key individually from the phase’s metadata.

schedule_details.phases.on_behalf_ofstringConnect only
The account on behalf of which to charge, for each of the associated subscription’s invoices.

schedule_details.phases.proration_behaviorenum

Whether the subscription schedule will create prorations when transitioning to this phase. The default value is create_prorations. This setting controls prorations when a phase is started asynchronously and it is persisted as a field on the phase. It’s different from the request-level proration_behavior parameter which controls what happens if the update request affects the billing configuration of the current phase.

Possible enum values

always_invoice

Prorate changes, and force an invoice to be immediately created for any prorations.

create_prorations

Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice.

none

Does not create any prorations.

schedule_details.phases.start_datetimestamp | string
The date at which this phase of the subscription schedule starts or now. Must be set on the first phase.

schedule_details.phases.transfer_dataobjectConnect only
The data with which to automatically create a Transfer for each of the associated subscription’s invoices.
- schedule_details.phases.transfer_data.destinationstringRequired
  ID of an existing, connected Stripe account.
- schedule_details.phases.transfer_data.amount_percentfloat
  A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the destination account. By default, the entire amount is transferred to the destination.

schedule_details.phases.trialboolean
If set to true the entire phase is counted as a trial and the customer will not be charged for any fees.

schedule_details.phases.trial_endtimestamp | string
Sets the phase to trialing from the start date to this date. Must be before the phase end date, can not be combined with trial

schedule_details.proration_behaviorenum

In cases where the schedule_details params update the currently active phase, specifies if and how to prorate at the time of the request.

Possible enum values

always_invoice

Prorate changes, and force an invoice to be created for those prorations instead of leaving the prorations pending.

create_prorations

Prorate changes, but leave any prorations as pending invoice items to be picked up on the customer’s next invoice.

none

Does not create any prorations.

subscription_billing_cycle_anchorstring | timestampDeprecated
For new subscriptions, a future timestamp to anchor the subscription’s billing cycle. This is used to determine the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to now or unchanged. This field has been deprecated and will be removed in a future API version. Use subscription_details.billing_cycle_anchor instead.

subscription_cancel_attimestampDeprecated
A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period. This field has been deprecated and will be removed in a future API version. Use subscription_details.cancel_at instead.

subscription_cancel_at_period_endbooleanDeprecated
Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false. This field has been deprecated and will be removed in a future API version. Use subscription_details.cancel_at_period_end instead.

subscription_cancel_nowbooleanDeprecated
This simulates the subscription being canceled or expired immediately. This field has been deprecated and will be removed in a future API version. Use subscription_details.cancel_now instead.

subscription_default_tax_ratesarray of stringsDeprecated
If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have tax_rates set. This field has been deprecated and will be removed in a future API version. Use subscription_details.default_tax_rates instead.

subscription_detailsobject

The subscription creation or modification params to apply as a preview. Cannot be used with schedule or schedule_details fields.

subscription_details.billing_cycle_anchorstring | timestamp
For new subscriptions, a future timestamp to anchor the subscription’s billing cycle. This is used to determine the date of the first full invoice, and, for plans with month or year intervals, the day of the month for subsequent invoices. For existing subscriptions, the value can only be set to now or unchanged.

subscription_details.cancel_attimestamp
A timestamp at which the subscription should cancel. If set to a date before the current period ends, this will cause a proration if prorations have been enabled using proration_behavior. If set during a future period, this will always cause a proration for that period.

subscription_details.cancel_at_period_endboolean
Indicate whether this subscription should cancel at the end of the current period (current_period_end). Defaults to false.

subscription_details.cancel_nowboolean
This simulates the subscription being canceled or expired immediately.

subscription_details.default_tax_ratesarray of strings
If provided, the invoice returned will preview updating or creating a subscription with these default tax rates. The default tax rates will apply to any line item that does not have tax_rates set.

subscription_details.itemsarray of objects
A list of up to 20 subscription items, each with an attached price.
- subscription_details.items.billing_thresholdsobject
  Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
  subscription_details.items.billing_thresholds.usage_gteintegerRequired
  Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 monetary threshold)
- subscription_details.items.clear_usageboolean
  Delete all usage for a given subscription item. Allowed only when deleted is set to true and the current plan’s usage_type is metered.
- subscription_details.items.deletedboolean
  A flag that, if set to true, will delete the specified item.
- subscription_details.items.discountsarray of objects
  The coupons to redeem into discounts for the subscription item.
  subscription_details.items.discounts.couponstring
  ID of the coupon to create a new discount for.
  subscription_details.items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  subscription_details.items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- subscription_details.items.idstring
  Subscription item to update.
- subscription_details.items.metadataobject
  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
- subscription_details.items.pricestring
  The ID of the price object. One of price or price_data is required. When changing a subscription item’s price, quantity is set to 1 unless a quantity parameter is provided.
- subscription_details.items.price_dataobject
  Data used to generate a new Price object inline. One of price or price_data is required.
  subscription_details.items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  subscription_details.items.price_data.productstringRequired
  The ID of the product that this price will belong to.
  subscription_details.items.price_data.recurringobjectRequired
  The recurring components of a price such as interval and interval_count.
  subscription_details.items.price_data.recurring.intervalenumRequired
  Specifies billing frequency. Either day, week, month or year.
  Possible enum values
  day
  month
  week
  year
  subscription_details.items.price_data.recurring.interval_countinteger
  The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
  subscription_details.items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  subscription_details.items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge.
  subscription_details.items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- subscription_details.items.quantityinteger
  Quantity for this item.
- subscription_details.items.tax_ratesarray of strings
  A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

subscription_details.proration_behaviorenum

Possible enum values

always_invoice

Always invoice immediately for prorations.

create_prorations

Will cause proration invoice items to be created when applicable. These proration items will only be invoiced immediately under certain conditions.

none

Disable creating prorations in this request.

subscription_details.proration_datetimestamp
If previewing an update to a subscription, and doing proration, subscription_details.proration_date forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, subscription, and one of subscription_details.items, or subscription_details.trial_end are required. Also, subscription_details.proration_behavior cannot be set to ‘none’.

subscription_details.resume_atstring
For paused subscriptions, setting subscription_details.resume_at to now will preview the invoice that will be generated if the subscription is resumed.

subscription_details.start_datetimestamp
Date a subscription is intended to start (can be future or past).

subscription_details.trial_endstring | timestamp
If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of subscription_details.items or subscription is required.

subscription_itemsarray of objectsDeprecated
A list of up to 20 subscription items, each with an attached price. This field has been deprecated and will be removed in a future API version. Use subscription_details.items instead.
- subscription_items.billing_thresholdsobject
  Define thresholds at which an invoice will be sent, and the subscription advanced to a new billing period. When updating, pass an empty string to remove previously-defined thresholds.
  subscription_items.billing_thresholds.usage_gteintegerRequired
  Number of units that meets the billing threshold to advance the subscription to a new billing period (e.g., it takes 10 $5 units to meet a $50 monetary threshold)
- subscription_items.clear_usageboolean
  Delete all usage for a given subscription item. Allowed only when deleted is set to true and the current plan’s usage_type is metered.
- subscription_items.deletedboolean
  A flag that, if set to true, will delete the specified item.
- subscription_items.discountsarray of objects
  The coupons to redeem into discounts for the subscription item.
  subscription_items.discounts.couponstring
  ID of the coupon to create a new discount for.
  subscription_items.discounts.discountstring
  ID of an existing discount on the object (or one of its ancestors) to reuse.
  subscription_items.discounts.promotion_codestring
  ID of the promotion code to create a new discount for.
- subscription_items.idstring
  Subscription item to update.
- subscription_items.metadataobject
  Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.
- subscription_items.pricestring
  The ID of the price object. One of price or price_data is required. When changing a subscription item’s price, quantity is set to 1 unless a quantity parameter is provided.
- subscription_items.price_dataobject
  Data used to generate a new Price object inline. One of price or price_data is required.
  subscription_items.price_data.currencyenumRequired
  Three-letter ISO currency code, in lowercase. Must be a supported currency.
  subscription_items.price_data.productstringRequired
  The ID of the product that this price will belong to.
  subscription_items.price_data.recurringobjectRequired
  The recurring components of a price such as interval and interval_count.
  subscription_items.price_data.recurring.intervalenumRequired
  Specifies billing frequency. Either day, week, month or year.
  Possible enum values
  day
  month
  week
  year
  subscription_items.price_data.recurring.interval_countinteger
  The number of intervals between subscription billings. For example, interval=month and interval_count=3 bills every 3 months. Maximum of three years interval allowed (3 years, 36 months, or 156 weeks).
  subscription_items.price_data.tax_behaviorenumRecommended if calculating taxes
  Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  Possible enum values
  exclusive
  inclusive
  unspecified
  subscription_items.price_data.unit_amountinteger
  A positive integer in cents (or 0 for a free price) representing how much to charge.
  subscription_items.price_data.unit_amount_decimalstringRequired conditionally
  Same as unit_amount, but accepts a decimal value in cents with at most 12 decimal places. Only one of unit_amount and unit_amount_decimal can be set.
- subscription_items.quantityinteger
  Quantity for this item.
- subscription_items.tax_ratesarray of strings
  A list of Tax Rate ids. These Tax Rates will override the default_tax_rates on the Subscription. When updating, pass an empty string to remove previously-defined tax rates.

subscription_proration_behaviorenumDeprecated

Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing_cycle_anchor=now, or starting a trial), or if an item’s quantity changes. The default value is create_prorations. This field has been deprecated and will be removed in a future API version. Use subscription_details.proration_behavior instead.

Possible enum values

always_invoice

Always invoice immediately for prorations.

create_prorations

Will cause proration invoice items to be created when applicable. These proration items will only be invoiced immediately under certain conditions.

none

Disable creating prorations in this request.

subscription_proration_datetimestampDeprecated
If previewing an update to a subscription, and doing proration, subscription_proration_date forces the proration to be calculated as though the update was done at the specified time. The time given must be within the current subscription period and within the current phase of the schedule backing this subscription, if the schedule exists. If set, subscription, and one of subscription_items, or subscription_trial_end are required. Also, subscription_proration_behavior cannot be set to ‘none’. This field has been deprecated and will be removed in a future API version. Use subscription_details.proration_date instead.

subscription_resume_atstringDeprecated
For paused subscriptions, setting subscription_resume_at to now will preview the invoice that will be generated if the subscription is resumed. This field has been deprecated and will be removed in a future API version. Use subscription_details.resume_at instead.

subscription_start_datetimestampDeprecated
Date a subscription is intended to start (can be future or past). This field has been deprecated and will be removed in a future API version. Use subscription_details.start_date instead.

subscription_trial_endstring | timestampDeprecated
If provided, the invoice returned will preview updating or creating a subscription with that trial end. If set, one of subscription_items or subscription is required. This field has been deprecated and will be removed in a future API version. Use subscription_details.trial_end instead.

Returns

Returns an invoice if valid customer information is provided. Raises an error otherwise.

GET /v1/invoices/upcoming

Server-side language

curl -G https://api.stripe.com/v1/invoices/upcoming \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d customer=cus_NeZwdNtLEOXuvB

Response

{
  "object": "invoice",
  "account_country": "US",
  "account_name": "Stripe Docs",
  "account_tax_ids": null,
  "amount_due": 0,
  "amount_paid": 0,
  "amount_remaining": 0,
  "amount_shipping": 0,
  "application": null,
  "application_fee_amount": null,
  "attempt_count": 0,
  "attempted": false,
  "auto_advance": false,
  "automatic_tax": {
    "enabled": false,
    "liability": null,
    "status": null
  },
  "billing_reason": "manual",
  "charge": null,
  "collection_method": "charge_automatically",
  "created": 1680644467,
  "currency": "usd",
  "custom_fields": null,
  "customer": "cus_NeZwdNtLEOXuvB",
  "customer_address": null,
  "customer_email": "jennyrosen@example.com",
  "customer_name": "Jenny Rosen",
  "customer_phone": null,
  "customer_shipping": null,
  "customer_tax_exempt": "none",
  "customer_tax_ids": [],
  "default_payment_method": null,
  "default_source": null,
  "default_tax_rates": [],
  "description": null,
  "discount": null,
  "discounts": [],
  "due_date": null,
  "ending_balance": null,
  "footer": null,
  "from_invoice": null,
  "hosted_invoice_url": null,
  "invoice_pdf": null,
  "issuer": {
    "type": "self"
  },
  "last_finalization_error": null,
  "latest_revision": null,
  "lines": {
    "object": "list",
    "data": [],
    "has_more": false,
    "total_count": 0,
    "url": "/v1/invoices/in_1MtHbELkdIwHu7ixl4OzzPMv/lines"
  },
  "livemode": false,
  "metadata": {},
  "next_payment_attempt": null,
  "number": null,
  "on_behalf_of": null,
  "paid": false,
  "paid_out_of_band": false,
  "payment_intent": null,
  "payment_settings": {
    "default_mandate": null,
    "payment_method_options": null,
    "payment_method_types": null
  },
  "period_end": 1680644467,
  "period_start": 1680644467,
  "post_payment_credit_notes_amount": 0,
  "pre_payment_credit_notes_amount": 0,
  "quote": null,
  "receipt_number": null,
  "rendering_options": null,
  "shipping_cost": null,
  "shipping_details": null,
  "starting_balance": 0,
  "statement_descriptor": null,
  "status": "draft",
  "status_transitions": {
    "finalized_at": null,
    "marked_uncollectible_at": null,
    "paid_at": null,
    "voided_at": null
  },
  "subscription": null,
  "subtotal": 0,
  "subtotal_excluding_tax": 0,
  "tax": null,
  "test_clock": null,
  "total": 0,
  "total_discount_amounts": [],
  "total_excluding_tax": 0,
  "total_tax_amounts": [],
  "transfer_data": null,
  "webhooks_delivered_at": 1680644467
}

Retrieve an upcoming invoice

Parameters

automatic_taxobject

automatic_tax.enabledbooleanRequired

automatic_tax.liabilityobjectConnect only

automatic_tax.liability.typeenumRequired

automatic_tax.liability.accountstringRequired only if type is account

customerstring

subscriptionstring

More parametersCollapse all

couponstringDeprecated

currencyenum

customer_detailsobject

customer_details.addressobjectRequired if calculating taxes

customer_details.address.citystring

customer_details.address.countrystringRequired for calculating taxes

customer_details.address.line1string

customer_details.address.line2string

customer_details.address.postal_codestringRequired for calculating taxes

customer_details.address.statestring

customer_details.shippingobject

customer_details.shipping.addressobjectRequired

customer_details.shipping.address.citystring

customer_details.shipping.address.countrystringRequired if calculating taxes

customer_details.shipping.address.line1string

customer_details.shipping.address.line2string

customer_details.shipping.address.postal_codestringRequired if calculating taxes

customer_details.shipping.address.statestring

customer_details.shipping.namestringRequired

customer_details.shipping.phonestring

customer_details.taxobject

customer_details.tax.ip_addressstring

customer_details.tax_exemptenum

customer_details.tax_idsarray of objects

customer_details.tax_ids.typestringRequired

customer_details.tax_ids.valuestringRequired

discountsarray of objects

discounts.couponstring

discounts.discountstring

discounts.promotion_codestring

invoice_itemsarray of objects

invoice_items.amountinteger

invoice_items.currencyenum

invoice_items.descriptionstring

invoice_items.discountableboolean

invoice_items.discountsarray of objects

invoice_items.discounts.couponstring

invoice_items.discounts.discountstring

invoice_items.discounts.promotion_codestring

invoice_items.invoiceitemstring

invoice_items.metadataobject

invoice_items.periodobject

invoice_items.period.endtimestampRequired

invoice_items.period.starttimestampRequired

invoice_items.pricestring

invoice_items.price_dataobject

invoice_items.price_data.currencyenumRequired

invoice_items.price_data.productstringRequired

invoice_items.price_data.tax_behaviorenumRecommended if calculating taxes

invoice_items.price_data.unit_amountinteger

invoice_items.price_data.unit_amount_decimalstringRequired conditionally

invoice_items.quantityinteger

invoice_items.tax_behaviorenumRecommended if calculating taxes

invoice_items.tax_codestringRecommended if calculating taxes

invoice_items.tax_ratesarray of strings

invoice_items.unit_amountinteger

invoice_items.unit_amount_decimalstring

issuerobjectConnect only

issuer.typeenumRequired

issuer.accountstringRequired only if type is account

on_behalf_ofstringConnect only

preview_modeenum

schedulestring

schedule_detailsobject

schedule_details.end_behaviorenum

schedule_details.phasesarray of objects

schedule_details.phases.itemsarray of objectsRequired

schedule_details.phases.items.billing_thresholdsobject

schedule_details.phases.items.billing_thresholds.usage_gteintegerRequired

schedule_details.phases.items.discountsarray of objects

More parameters