# Retrieve an upcoming invoice's line items

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.

## Prerequisites

Before you can run the following code snippet, you need to call these APIs with the provided parameters to set up the prerequisite API object(s).

1. createCustomer
POST /v1/customers {"name":"Jenny Rosen","email":"jennyrosen@example.com"}

## Request

```curl
curl -G https://api.stripe.com/v1/invoices/upcoming/lines \
  -u "<<YOUR_SECRET_KEY>>" \
  -d customer={{CUSTOMER_ID}}
```

### Response

```json
{
  "object": "list",
  "url": "/v1/invoices/upcoming/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_tmp_1NtH5qBHO5VeT9SUzhbifVXt",
      "object": "line_item",
      "amount": 1000,
      "amount_excluding_tax": 1000,
      "currency": "usd",
      "description": "My First Invoice Item (created for API docs)",
      "discount_amounts": [],
      "discountable": true,
      "discounts": [],
      "invoice_item": "ii_1NtH5qBHO5VeT9SUzhbifVXt",
      "livemode": false,
      "metadata": {},
      "period": {
        "end": 1695418858,
        "start": 1695418858
      },
      "price": {
        "id": "price_1NrpbEBHO5VeT9SUHp6xMwKA",
        "object": "price",
        "active": true,
        "billing_scheme": "per_unit",
        "created": 1695074844,
        "currency": "usd",
        "custom_unit_amount": null,
        "livemode": false,
        "lookup_key": null,
        "metadata": {},
        "nickname": null,
        "product": "prod_Of9vdHHGRaGOio",
        "recurring": null,
        "tax_behavior": "unspecified",
        "tiers_mode": null,
        "transform_quantity": null,
        "type": "one_time",
        "unit_amount": 1000,
        "unit_amount_decimal": "1000"
      },
      "proration": false,
      "proration_details": {
        "credited_items": null
      },
      "quantity": 1,
      "subscription": null,
      "tax_amounts": [],
      "tax_rates": [],
      "type": "invoiceitem",
      "unit_amount_excluding_tax": "1000"
    }
  ]
}
```

## Returns

Returns a list of [line_item objects](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?api-version=2024-12-18.acacia#invoice_line_item_object).

## Parameters

- [`automatic_tax`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=automatic_tax&api-version=2024-12-18.acacia) (object, optional)
  Settings for automatic tax lookup for this invoice preview.

- `coupon` (string, optional)
  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.

- `currency` (enum, optional)
  The currency to preview this invoice in. Defaults to that of `customer` if not specified.

- `customer` (string, optional)
  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`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=customer_details&api-version=2024-12-18.acacia) (object, optional)
  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`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=discounts&api-version=2024-12-18.acacia) (array of objects, optional)
  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.

- `ending_before` (string, optional)
  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.

- [`invoice_items`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=invoice_items&api-version=2024-12-18.acacia) (array of objects, optional)
  List of invoice items to add or update in the upcoming invoice preview (up to 250).

- [`issuer`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=issuer&api-version=2024-12-18.acacia) (object, optional)
  The connected account that issues the invoice. The invoice is presented with the branding and support information of the specified account.

- `limit` (integer, optional)
  A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

- `on_behalf_of` (string, optional)
  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](https://docs.stripe.com/docs/billing/invoices/connect.md?api-version=2024-12-18.acacia) documentation for details.

- `preview_mode` (enum, optional)
  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.

- `schedule` (string, optional)
  The identifier of the schedule whose upcoming invoice you’d like to retrieve. Cannot be used with subscription or subscription fields.

- [`schedule_details`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=schedule_details&api-version=2024-12-18.acacia) (object, optional)
  The schedule creation or modification params to apply as a preview. Cannot be used with `subscription` or `subscription_` prefixed fields.

- `starting_after` (string, optional)
  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, optional)
  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.

- `subscription_billing_cycle_anchor` (string | timestamp, optional)
  For new subscriptions, a future timestamp to anchor the subscription’s [billing cycle](https://docs.stripe.com/docs/subscriptions/billing-cycle.md?api-version=2024-12-18.acacia). 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_at` (timestamp, optional)
  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_end` (boolean, optional)
  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_now` (boolean, optional)
  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_rates` (array of strings, optional)
  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_details`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=subscription_details&api-version=2024-12-18.acacia) (object, optional)
  The subscription creation or modification params to apply as a preview. Cannot be used with `schedule` or `schedule_details` fields.

- [`subscription_items`](https://docs.stripe.com/api/invoice-line-item/invoices/upcoming/lines/retrieve.md?query=subscription_items&api-version=2024-12-18.acacia) (array of objects, optional)
  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_proration_behavior` (enum, optional)
  Determines how to handle [prorations](https://docs.stripe.com/docs/billing/subscriptions/prorations.md?api-version=2024-12-18.acacia) 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](https://docs.stripe.com/docs/subscriptions/upgrading-downgrading.md?api-version=2024-12-18.acacia#immediate-payment).

  - `none`
    Disable creating prorations in this request.

- `subscription_proration_date` (timestamp, optional)
  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_at` (string, optional)
  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_date` (timestamp, optional)
  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_end` (string | timestamp, optional)
  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.