Retrieve an upcoming invoice's line items

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

When retrieving an upcoming invoice, you’ll get a lines property containing the total count of line items and the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.

Request Params

KeyDatatypeRequiredDescription
automatic_tax[enabled]stringSettings for automatic tax lookup for this invoice preview.
automatic_tax[liability][type]stringSettings for automatic tax lookup for this invoice preview.
automatic_tax[liability][account]stringSettings for automatic tax lookup for this invoice preview.
couponstringThe 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.
currencystringThe currency to preview this invoice in. Defaults to that of customer if not specified.
customerstringThe 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.
customer_details[address][city]stringDetails 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[address][country]stringDetails 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[address][line1]stringDetails 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[address][line2]stringDetails 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[address][postal_code]stringDetails 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[address][state]stringDetails 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[shipping][address][city]stringDetails 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[shipping][address][country]stringDetails 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[shipping][address][line1]stringDetails 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[shipping][address][line2]stringDetails 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[shipping][address][postal_code]stringDetails 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[shipping][address][state]stringDetails 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[shipping][name]stringDetails 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[shipping][phone]stringDetails 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[tax][ip_address]stringDetails 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[tax_exempt]stringDetails 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[tax_ids][0][type]stringDetails 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[tax_ids][0][value]stringDetails 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[tax_ids][1][type]stringDetails 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[tax_ids][1][value]stringDetails 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.
discounts[0][coupon]stringThe 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[0][discount]stringThe 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[0][promotion_code]stringThe 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[1][coupon]stringThe 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[1][discount]stringThe 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[1][promotion_code]stringThe 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.
ending_beforestringA cursor for use in pagination. ending_before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_bar, your subsequent call can include ending_before=obj_bar in order to fetch the previous page of the list.
expand[0]stringSpecifies which fields in the response should be expanded.
expand[1]stringSpecifies which fields in the response should be expanded.
invoice_items[0][amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][currency]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][description]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discountable]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][0][coupon]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][0][discount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][0][promotion_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][1][coupon]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][1][discount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][discounts][1][promotion_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][invoiceitem]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][metadata]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][period][end]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][period][start]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price_data][currency]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price_data][product]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price_data][tax_behavior]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price_data][unit_amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][price_data][unit_amount_decimal]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][quantity]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][tax_behavior]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][tax_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][tax_rates][0]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][tax_rates][1]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][unit_amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[0][unit_amount_decimal]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][currency]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][description]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discountable]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][0][coupon]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][0][discount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][0][promotion_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][1][coupon]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][1][discount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][discounts][1][promotion_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][invoiceitem]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][metadata]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][period][end]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][period][start]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price_data][currency]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price_data][product]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price_data][tax_behavior]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price_data][unit_amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][price_data][unit_amount_decimal]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][quantity]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][tax_behavior]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][tax_code]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][tax_rates][0]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][tax_rates][1]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][unit_amount]stringList of invoice items to add or update in the upcoming invoice preview.
invoice_items[1][unit_amount_decimal]stringList of invoice items to add or update in the upcoming invoice preview.
issuer[type]stringThe connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
issuer[account]stringThe connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.
limitstringA limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
schedulestringThe identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields.
starting_afterstringA cursor for use in pagination. starting_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include starting_after=obj_foo in order to fetch the next page of the list.
subscriptionstringThe 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_endstringBoolean indicating whether this subscription should cancel at the end of the current period.
subscription_cancel_nowstringThis simulates the subscription being canceled or expired immediately.
subscription_default_tax_rates[0]stringIf 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]stringIf 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]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][clear_usage]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][deleted]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][0][coupon]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][0][discount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][0][promotion_code]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][1][coupon]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][1][discount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][discounts][1][promotion_code]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][id]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][metadata]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][currency]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][product]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][recurring][interval]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][recurring][interval_count]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][tax_behavior]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][unit_amount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][price_data][unit_amount_decimal]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][quantity]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][tax_rates][0]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[0][tax_rates][1]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][billing_thresholds][usage_gte]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][clear_usage]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][deleted]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][0][coupon]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][0][discount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][0][promotion_code]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][1][coupon]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][1][discount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][discounts][1][promotion_code]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][id]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][metadata]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][currency]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][product]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][recurring][interval]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][recurring][interval_count]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][tax_behavior]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][unit_amount]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][price_data][unit_amount_decimal]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][quantity]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][tax_rates][0]stringA list of up to 20 subscription items, each with an attached price.
subscription_items[1][tax_rates][1]stringA list of up to 20 subscription items, each with an attached price.
subscription_proration_behaviorstringDetermines 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.
subscription_proration_datestringIf 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'.
subscription_resume_atstringFor paused subscriptions, setting subscription_resume_at to now will preview the invoice that will be generated if the subscription is resumed.
subscription_start_datestringDate a subscription is intended to start (can be future or past).
subscription_trial_from_planstringIndicates 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

KeyDatatypeRequiredDescription
Content-Typestring