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
Key | Datatype | Required | Description |
---|---|---|---|
automatic_tax[enabled] | string | Settings for automatic tax lookup for this invoice preview. | |
automatic_tax[liability][type] | string | Settings for automatic tax lookup for this invoice preview. | |
automatic_tax[liability][account] | 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. If automatic_tax is enabled then one of customer , customer_details , subscription , or schedule must be set. | |
customer_details[address][city] | string | 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[address][country] | string | 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[address][line1] | string | 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[address][line2] | string | 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[address][postal_code] | string | 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[address][state] | string | 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[shipping][address][city] | string | 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[shipping][address][country] | string | 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[shipping][address][line1] | string | 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[shipping][address][line2] | string | 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[shipping][address][postal_code] | string | 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[shipping][address][state] | string | 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[shipping][name] | string | 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[shipping][phone] | string | 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[tax][ip_address] | string | 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[tax_exempt] | string | 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[tax_ids][0][type] | string | 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[tax_ids][0][value] | string | 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[tax_ids][1][type] | string | 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[tax_ids][1][value] | string | 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. | |
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[0][promotion_code] | 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. | |
discounts[1][promotion_code] | 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. | |
ending_before | string | A 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] | 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][0][promotion_code] | 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][discounts][1][promotion_code] | 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][0][promotion_code] | 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][discounts][1][promotion_code] | 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. | |
issuer[type] | string | The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. | |
issuer[account] | string | The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account. | |
limit | string | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. | |
schedule | string | The identifier of the schedule whose upcoming invoice you'd like to retrieve. Cannot be used with subscription or subscription fields. | |
starting_after | string | A 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. | |
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. The default value is create_prorations . | |
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 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_at | string | For paused subscriptions, setting subscription_resume_at to now will preview the invoice that will be generated if the subscription is resumed. | |
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 |