---
title: "List all subscription items"
method: GET
path: "/v1/subscription_items"
---

# List all subscription items

`GET /v1/subscription_items`

Returns a list of your subscription items for a given subscription.

## Query parameters

- `ending_before` string
- `expand` string[]
- `limit` integer
- `starting_after` string
- `subscription` string, required

## Response `200`

Successful response.

- object
  - `data` SubscriptionItem[], required
    - `billed_until` integer — The time period the subscription item has been billed for.
    - `billing_thresholds` SubscriptionItemBillingThresholds
      - `usage_gte` integer, nullable — Usage threshold that triggers the subscription to create an invoice
    - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
    - `current_period_end` integer, required — The end time of this subscription item's current billing period.
    - `current_period_start` integer, required — The start time of this subscription item's current billing period.
    - `discounts` union[], required — The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use `expand[]=discounts` to expand each discount.
      - union
        - string
        - Discount — A discount represents the actual application of a [coupon](https://api.stripe.com#coupons) or [promotion code](https://api.stripe.com#promotion_codes). It contains information about when the discount began, when it will end, and what it is applied to. Related guide: [Applying discounts to subscriptions](https://docs.stripe.com/billing/subscriptions/discounts)
          - `checkout_session` string, nullable — The Checkout session that this coupon is applied to, if it is applied to a particular session in payment mode. Not present for subscription mode.
          - `customer` union — The ID of the customer associated with this discount.
            - string
            - Customer — This object represents a customer of your business. Use it to [create recurring charges](https://docs.stripe.com/invoicing/customer), [save payment](https://docs.stripe.com/payments/save-during-payment) and contact information, and track payments that belong to the same customer.
              - …
            - DeletedCustomer
              - …
          - `customer_account` string, nullable — The ID of the account representing the customer associated with this discount.
          - `end` integer, nullable — If the coupon has a duration of `repeating`, the date that this discount will end. If the coupon has a duration of `once` or `forever`, this attribute will be null.
          - `id` string, required — The ID of the discount object. Discounts can't be fetched by ID. Use `expand[]=discounts` in API calls to expand discount IDs in an array.
          - `invoice` string, nullable — The invoice that the discount's coupon was applied to, if it was applied directly to a particular invoice.
          - `invoice_item` string, nullable — The invoice item `id` (or invoice line item `id` for invoice line items of type='subscription') that the discount's coupon was applied to, if it was applied directly to a particular invoice item or invoice line item.
          - `object` 'discount', required — String representing the object's type. Objects of the same type share the same value.
          - `promotion_code` union — The promotion code applied to create this discount.
            - string
            - PromotionCode — A Promotion Code represents a customer-redeemable code for an underlying promotion. You can create multiple codes for a single promotion. If you enable promotion codes in your [customer portal configuration](https://docs.stripe.com/customer-management/configure-portal), then customers can redeem a code themselves when updating a subscription in the portal. Customers can also view the currently active promotion codes and coupons on each of their subscriptions in the portal.
              - …
          - `source` DiscountSource, required
            - `coupon` union — The coupon that was redeemed to create this discount.
              - …
            - `type` 'coupon', required — The source type of the discount.
          - `start` integer, required — Date that the coupon was applied.
          - `subscription` string, nullable — The subscription that this coupon is applied to, if it is applied to a particular subscription.
          - `subscription_item` string, nullable — The subscription item that this coupon is applied to, if it is applied to a particular subscription item.
    - `id` string, required — Unique identifier for the object.
    - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
    - `object` 'subscription_item', required — String representing the object's type. Objects of the same type share the same value.
    - `price` Price, required — Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. [Products](https://api.stripe.com#products) help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme. For example, you might have a single "gold" product that has prices for $10/month, $100/year, and €9 once. Related guides: [Set up a subscription](https://docs.stripe.com/billing/subscriptions/set-up-subscription), [create an invoice](https://docs.stripe.com/billing/invoices/create), and more about [products and prices](https://docs.stripe.com/products-prices/overview).
      - `active` boolean, required — Whether the price can be used for new purchases.
      - `billing_scheme` 'per_unit' | 'tiered', required — Describes how to compute the price per period. Either `per_unit` or `tiered`. `per_unit` indicates that the fixed amount (specified in `unit_amount` or `unit_amount_decimal`) will be charged per unit in `quantity` (for prices with `usage_type=licensed`), or per unit of total usage (for prices with `usage_type=metered`). `tiered` indicates that the unit pricing will be computed using a tiering strategy as defined using the `tiers` and `tiers_mode` attributes.
      - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
      - `currency` string, currency, required — Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).
      - `currency_options` object — Prices defined in each available currency option. Each key must be a three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) and a [supported currency](https://stripe.com/docs/currencies).
      - `custom_unit_amount` CustomUnitAmount
        - `maximum` integer, nullable — The maximum unit amount the customer can specify for this item.
        - `minimum` integer, nullable — The minimum unit amount the customer can specify for this item. Must be at least the minimum charge amount.
        - `preset` integer, nullable — The starting unit amount which can be updated by the customer.
      - `id` string, required — Unique identifier for the object.
      - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
      - `lookup_key` string, nullable — A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters.
      - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
      - `nickname` string, nullable — A brief description of the price, hidden from customers.
      - `object` 'price', required — String representing the object's type. Objects of the same type share the same value.
      - `product` union, required — The ID of the product this price is associated with.
        - string
        - Product — Products describe the specific goods or services you offer to your customers. For example, you might offer a Standard and Premium version of your goods or service; each version would be a separate Product. They can be used in conjunction with [Prices](https://api.stripe.com#prices) to configure pricing in Payment Links, Checkout, and Subscriptions. Related guides: [Set up a subscription](https://docs.stripe.com/billing/subscriptions/set-up-subscription), [share a Payment Link](https://docs.stripe.com/payment-links), [accept payments with Checkout](https://docs.stripe.com/payments/accept-a-payment#create-product-prices-upfront), and more about [Products and Prices](https://docs.stripe.com/products-prices/overview)
          - `active` boolean, required — Whether the product is currently available for purchase.
          - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
          - `default_price` union — The ID of the [Price](https://docs.stripe.com/api/prices) object that is the default price for this product.
            - string
            - Price — recursive
          - `description` string, nullable — The product's description, meant to be displayable to the customer. Use this field to optionally store a long form explanation of the product being sold for your own rendering purposes.
          - `id` string, required — Unique identifier for the object.
          - `images` string[], required — A list of up to 8 URLs of images for this product, meant to be displayable to the customer.
          - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
          - `marketing_features` ProductMarketingFeature[], required — A list of up to 15 marketing features for this product. These are displayed in [pricing tables](https://docs.stripe.com/payments/checkout/pricing-table).
            - `name` string — The marketing feature name. Up to 80 characters long.
          - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
          - `name` string, required — The product's name, meant to be displayable to the customer.
          - `object` 'product', required — String representing the object's type. Objects of the same type share the same value.
          - `package_dimensions` PackageDimensions
            - `height` number, required — Height, in inches.
            - `length` number, required — Length, in inches.
            - `weight` number, required — Weight, in ounces.
            - `width` number, required — Width, in inches.
          - `shippable` boolean, nullable — Whether this product is shipped (i.e., physical goods).
          - `statement_descriptor` string, nullable — Extra information about a product which will appear on your customer's credit card statement. In the case that multiple products are billed at once, the first statement descriptor will be used. Only used for subscription payments.
          - `tax_code` union — A [tax code](https://docs.stripe.com/tax/tax-categories) ID.
            - string
            - TaxCode — [Tax codes](https://stripe.com/docs/tax/tax-categories) classify goods and services for tax purposes.
              - …
          - `unit_label` string, nullable — A label that represents units of this product. When set, this will be included in customers' receipts, invoices, Checkout, and the customer portal.
          - `updated` integer, required — Time at which the object was last updated. Measured in seconds since the Unix epoch.
          - `url` string, nullable — A URL of a publicly-accessible webpage for this product.
        - DeletedProduct
          - `deleted` true, required — Always true for a deleted object
          - `id` string, required — Unique identifier for the object.
          - `object` 'product', required — String representing the object's type. Objects of the same type share the same value.
      - `recurring` Recurring
        - `interval` 'day' | 'month' | 'week' | 'year', required — The frequency at which a subscription is billed. One of `day`, `week`, `month` or `year`.
        - `interval_count` integer, required — The number of intervals (specified in the `interval` attribute) between subscription billings. For example, `interval=month` and `interval_count=3` bills every 3 months.
        - `meter` string, nullable — The meter tracking the usage of a metered price
        - `usage_type` 'licensed' | 'metered', required — Configures how the quantity per period should be determined. Can be either `metered` or `licensed`. `licensed` automatically bills the `quantity` set when adding it to a subscription. `metered` aggregates the total usage based on usage records. Defaults to `licensed`.
      - `tax_behavior` 'exclusive' | 'inclusive' | 'unspecified', nullable — Only required if a [default tax behavior](https://docs.stripe.com/tax/products-prices-tax-categories-tax-behavior#setting-a-default-tax-behavior-(recommended)) 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.
      - `tiers` PriceTier[] — Each element represents a pricing tier. This parameter requires `billing_scheme` to be set to `tiered`. See also the documentation for `billing_scheme`.
        - `flat_amount` integer, nullable — Price for the entire tier.
        - `flat_amount_decimal` string, decimal, nullable — Same as `flat_amount`, but contains a decimal value with at most 12 decimal places.
        - `unit_amount` integer, nullable — Per unit price for units relevant to the tier.
        - `unit_amount_decimal` string, decimal, nullable — Same as `unit_amount`, but contains a decimal value with at most 12 decimal places.
        - `up_to` integer, nullable — Up to and including to this quantity will be contained in the tier.
      - `tiers_mode` 'graduated' | 'volume', nullable — Defines if the tiering price should be `graduated` or `volume` based. In `volume`-based tiering, the maximum quantity within a period determines the per unit price. In `graduated` tiering, pricing can change as the quantity grows.
      - `transform_quantity` TransformQuantity
        - `divide_by` integer, required — Divide usage by this number.
        - `round` 'down' | 'up', required — After division, either round the result `up` or `down`.
      - `type` 'one_time' | 'recurring', required — One of `one_time` or `recurring` depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
      - `unit_amount` integer, nullable — The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if `billing_scheme=per_unit`.
      - `unit_amount_decimal` string, decimal, nullable — The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if `billing_scheme=per_unit`.
    - `quantity` integer — The [quantity](https://docs.stripe.com/subscriptions/quantities) of the plan to which the customer should be subscribed.
    - `subscription` string, required — The `subscription` this `subscription_item` belongs to.
    - `tax_rates` TaxRate[], nullable — The tax rates which apply to this `subscription_item`. When set, the `default_tax_rates` on the subscription do not apply to this `subscription_item`.
      - `active` boolean, required — Defaults to `true`. When set to `false`, this tax rate cannot be used with new applications or Checkout Sessions, but will still work for subscriptions and invoices that already have it set.
      - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
      - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
      - `description` string, nullable — An arbitrary string attached to the tax rate for your internal use only. It will not be visible to your customers.
      - `display_name` string, required — The display name of the tax rates as it will appear to your customer on their receipt email, PDF, and the hosted invoice page.
      - `effective_percentage` number, nullable — Actual/effective tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage reflects the rate actually used to calculate tax based on the product's taxability and whether the user is registered to collect taxes in the corresponding jurisdiction.
      - `flat_amount` TaxRateFlatAmount — The amount of the tax rate when the `rate_type`` is `flat_amount`. Tax rates with `rate_type` `percentage` can vary based on the transaction, resulting in this field being `null`. This field exposes the amount and currency of the flat tax rate.
        - `amount` integer, required — Amount of the tax when the `rate_type` is `flat_amount`. This positive integer represents how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
        - `currency` string, required — Three-letter ISO currency code, in lowercase.
      - `id` string, required — Unique identifier for the object.
      - `inclusive` boolean, required — This specifies if the tax rate is inclusive or exclusive.
      - `jurisdiction` string, nullable — The jurisdiction for the tax rate. You can use this label field for tax reporting purposes. It also appears on your customer’s invoice.
      - `jurisdiction_level` 'city' | 'country' | 'county' | 'district' | 'multiple' | 'state', nullable — The level of the jurisdiction that imposes this tax rate. Will be `null` for manually defined tax rates.
      - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
      - `metadata` object, nullable — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
      - `object` 'tax_rate', required — String representing the object's type. Objects of the same type share the same value.
      - `percentage` number, required — Tax rate percentage out of 100. For tax calculations with automatic_tax[enabled]=true, this percentage includes the statutory tax rate of non-taxable jurisdictions.
      - `rate_type` 'flat_amount' | 'percentage', nullable — Indicates the type of tax rate applied to the taxable amount. This value can be `null` when no tax applies to the location. This field is only present for TaxRates created by Stripe Tax.
      - `state` string, nullable — [ISO 3166-2 subdivision code](https://en.wikipedia.org/wiki/ISO_3166-2), without country prefix. For example, "NY" for New York, United States.
      - `tax_type` 'amusement_tax' | 'communications_tax' | 'gst' | 'hst' | 'igst' | 'jct' | 'lease_tax' | 'mass_transit_parking_tax' | 'parking_tax' | 'pst' | 'qst' | 'retail_delivery_fee' | 'rst' | 'sales_tax' | 'service_tax' | 'vat', nullable — The high-level tax type, such as `vat` or `sales_tax`.
  - `has_more` boolean, required — True if this list has another page of items after this one that can be fetched.
  - `object` 'list', required — String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
  - `url` string, required — The URL where this list can be accessed.

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/stripe/apis/stripe-api.md) · [All operations](https://skmtc.net/stripe/apis/stripe-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stripe/stripe-api/versions/707de00b0616/schema)