Retrieve an upcoming invoice

GET {{baseUrl}}/v1/invoices/upcoming

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 a proration_date parameter when doing the actual subscription update. The value passed in should be the same as the subscription_proration_date returned on the upcoming invoice resource. 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_proration_date on the upcoming invoice resource.

Request Params

Key	Datatype	Description
`automatic_tax[enabled]`	string	Settings for automatic tax lookup for this invoice preview.
`coupon`	string	The code of the coupon to apply. If `subscription` or `subscription_items` is provided, the invoice returned will preview updating or creating a subscription with that coupon. Otherwise, it will preview applying that coupon to the customer for the next upcoming invoice from among the customer's subscriptions. The invoice can be previewed without a coupon by passing this value as an empty string.
`currency`	string	The currency to preview this invoice in. Defaults to that of `customer` if not specified.
`customer`	string	The identifier of the customer whose upcoming invoice you'd like to retrieve.
`customer_details[address][city]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[address][country]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[address][line1]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[address][line2]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[address][postal_code]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[address][state]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][city]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][country]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][line1]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][line2]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][postal_code]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][address][state]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][name]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[shipping][phone]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax][ip_address]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax_exempt]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax_ids][0][type]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax_ids][0][value]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax_ids][1][type]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`customer_details[tax_ids][1][value]`	string	Details about the customer you want to invoice or overrides for an existing customer.
`discounts[0][coupon]`	string	The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the customer or subscription. This only works for coupons directly applied to the invoice. To apply a coupon to a subscription, you must use the `coupon` parameter instead. Pass an empty string to avoid inheriting any discounts. To preview the upcoming invoice for a subscription that hasn't been created, use `coupon` instead.
`discounts[0][discount]`	string	The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the customer or subscription. This only works for coupons directly applied to the invoice. To apply a coupon to a subscription, you must use the `coupon` parameter instead. Pass an empty string to avoid inheriting any discounts. To preview the upcoming invoice for a subscription that hasn't been created, use `coupon` instead.
`discounts[1][coupon]`	string	The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the customer or subscription. This only works for coupons directly applied to the invoice. To apply a coupon to a subscription, you must use the `coupon` parameter instead. Pass an empty string to avoid inheriting any discounts. To preview the upcoming invoice for a subscription that hasn't been created, use `coupon` instead.
`discounts[1][discount]`	string	The coupons to redeem into discounts for the invoice preview. If not specified, inherits the discount from the customer or subscription. This only works for coupons directly applied to the invoice. To apply a coupon to a subscription, you must use the `coupon` parameter instead. Pass an empty string to avoid inheriting any discounts. To preview the upcoming invoice for a subscription that hasn't been created, use `coupon` instead.
`expand[0]`	string	Specifies which fields in the response should be expanded.
`expand[1]`	string	Specifies which fields in the response should be expanded.
`invoice_items[0][amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][currency]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][description]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][discountable]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][discounts][0][coupon]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][discounts][0][discount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][discounts][1][coupon]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][discounts][1][discount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][invoiceitem]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][metadata]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][period][end]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][period][start]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price_data][currency]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price_data][product]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price_data][tax_behavior]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price_data][unit_amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][price_data][unit_amount_decimal]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][quantity]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][tax_behavior]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][tax_code]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][tax_rates][0]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][tax_rates][1]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][unit_amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[0][unit_amount_decimal]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][currency]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][description]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][discountable]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][discounts][0][coupon]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][discounts][0][discount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][discounts][1][coupon]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][discounts][1][discount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][invoiceitem]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][metadata]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][period][end]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][period][start]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price_data][currency]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price_data][product]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price_data][tax_behavior]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price_data][unit_amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][price_data][unit_amount_decimal]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][quantity]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][tax_behavior]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][tax_code]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][tax_rates][0]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][tax_rates][1]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][unit_amount]`	string	List of invoice items to add or update in the upcoming invoice preview.
`invoice_items[1][unit_amount_decimal]`	string	List of invoice items to add or update in the upcoming invoice preview.
`schedule`	string	The identifier of the unstarted schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
`subscription`	string	The identifier of the subscription for which you'd like to retrieve the upcoming invoice. If not provided, but a `subscription_items` is provided, you will preview creating a subscription with those items. If neither `subscription` nor `subscription_items` is provided, you will retrieve the next upcoming invoice from among the customer's subscriptions.
`subscription_cancel_at_period_end`	string	Boolean indicating whether this subscription should cancel at the end of the current period.
`subscription_cancel_now`	string	This simulates the subscription being canceled or expired immediately.
`subscription_default_tax_rates[0]`	string	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_default_tax_rates[1]`	string	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_items[0][billing_thresholds][usage_gte]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][clear_usage]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][deleted]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][id]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][metadata]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][currency]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][product]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][recurring][interval]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][recurring][interval_count]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][tax_behavior]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][unit_amount]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][price_data][unit_amount_decimal]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][quantity]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][tax_rates][0]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[0][tax_rates][1]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][billing_thresholds][usage_gte]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][clear_usage]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][deleted]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][id]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][metadata]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][currency]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][product]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][recurring][interval]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][recurring][interval_count]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][tax_behavior]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][unit_amount]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][price_data][unit_amount_decimal]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][quantity]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][tax_rates][0]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_items[1][tax_rates][1]`	string	A list of up to 20 subscription items, each with an attached price.
`subscription_proration_behavior`	string	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.
`subscription_proration_date`	string	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 cannot be before the subscription was on its current plan. If set, `subscription`, and one of `subscription_items`, or `subscription_trial_end` are required. Also, `subscription_proration_behavior` cannot be set to 'none'.
`subscription_start_date`	string	Date a subscription is intended to start (can be future or past)
`subscription_trial_from_plan`	string	Indicates if a plan's `trial_period_days` should be applied to the subscription. Setting `subscription_trial_end` per subscription is preferred, and this defaults to `false`. Setting this flag to `true` together with `subscription_trial_end` is not allowed. See Using trial periods on subscriptions to learn more.

HEADERS

Key	Datatype	Required	Description
`Content-Type`	string