--- title: "List Subscriptions" method: GET path: "/v1/subscriptions" tags: ["Subscriptions"] --- # List Subscriptions `GET /v1/subscriptions` Returns a list of your subscriptions, most recent first. Optionally filter by customer or status. Use `expand` (or `expand_customer`) to inline related objects such as the customer, latest invoice, or item prices. ## Query parameters - `customer` string, nullable — Filter by customer ID. - `expand_customer` boolean, nullable — If true, expands the customer object in the response. - `starting_after` string, nullable — A cursor for use in pagination. `starting_after` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, ending with `fsub_xyz`, your subsequent call can include `starting_after=fsub_xyz` to fetch the next page. - `ending_before` string, nullable — A cursor for use in pagination. `ending_before` is a subscription ID that defines your place in the list. For instance, if you make a list request and receive 20 subscriptions, starting with `fsub_abc`, your subsequent call can include `ending_before=fsub_abc` to fetch the previous page. - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused' — The current lifecycle status of the subscription. - `offset` integer, nullable — Number of objects to skip before returning results. - `limit` integer, nullable — A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. - `expand` string — Comma-separated list of related objects to expand in the response. ## Response `200` An envelope wrapping a list of subscription objects. - MultipleSubscriptionBodyForArrayOfSubscription — An envelope wrapping a list of subscription objects. - `subscriptions` Subscription[], required — The list of subscriptions. - `subscription_id` string, required — Unique identifier for the object. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `items` V1SubscriptionItem[], required — The items the customer is subscribed to. - `subscription_item_id` string, required — Unique identifier for the subscription item. - `price` union, required — An expandable field — either a string ID or an expanded Price object. - string - Price — Prices define the unit cost and (optional) billing cycle for both recurring and one-time purchases of products. Prices belong to a given product. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. - `price_id` string, required — The unique identifier for the price. - `owner_partner_id` string, nullable — The ID of the account that owns this price. For prices shared across an organization this may be a sibling account; otherwise it is your own account ID. - `description` string, nullable — The description of the price. - `trial_period_days` integer, nullable — The number of trial period days before the customer is first charged for a recurring price. - `unit_amount` integer, required — The amount to charge per unit, in the smallest currency unit (e.g., `2500` = $25.00 USD). - `recurring` Recurring — Describes how a recurring price bills over time. Present on prices of type `recurring`; `null` for one-time prices. - `interval` 'day' | 'week' | 'month' | 'year', required — The frequency at which a recurring price bills. - `interval_count` integer, nullable — The number of intervals - `trial_period_days` integer, nullable — The number of trial period days before the customer is charged for the first time. Whole days only. For a precise trial-end timestamp (e.g. non-integer days), use `subscription_data.trial_end` on the Create Checkout Session request instead. - `active` boolean, required — Whether the price is currently active. - `product` union, required — An expandable field — either a string ID or an expanded Product object. - string - Product — A Product defines what you sell. Flex determines its HSA/FSA eligibility from the name, description, and identifiers you provide. - … - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `type` 'one_time' | 'recurring', required — Whether the price is charged once or on a recurring schedule. - `metadata` object, nullable — Metadata information for the price object - `hsa_fsa_eligibility` 'not_eligible' | 'auto_substantiation' | 'private_label' | 'letter_of_medical_necessity' | 'prescription' | 'vision' | 'service' | 'pending' — How a product qualifies for HSA/FSA payment, which determines the substantiation required to pay with a benefits card. `pending` means the product is still awaiting Flex's automatic classification, so its eligibility is not yet determined. - `test_mode` boolean, required — Whether the price is in test mode. - `quantity` integer, required — The number of units of the price the customer is subscribed to. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `updated_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the subscription item exists in test mode. - `latest_invoice` union — An expandable field — either a string ID or an expanded Invoice object. - string - Invoice — An Invoice is a statement of the amounts owed by a customer, generated when a subscription advances through its billing cycle. It tracks the total, amount due, and amount paid, along with the payment intent, charge, and billing period that produced it, and its current lifecycle status as it is finalized and collected. - `invoice_id` string, required — The id of the invoice. - `total` integer, required — The total amount of the invoice in cents. - `amount_due` integer, required — The amount due in cents. - `amount_paid` integer, required — The amount paid in cents. - `payment_intent` union — An expandable field — either a string ID or an expanded PaymentIntent object. - string - PaymentIntent — A PaymentIntent tracks Flex's process of collecting a payment from a customer: the amount to collect, its lifecycle status, and references to the customer, payment method, and resulting charge. A single PaymentIntent may produce several charges over its lifetime (for example after a retry); the most recent is referenced by `latest_charge`. - `payment_intent_id` string, required — The unique identifier for the payment intent. - `amount` integer, required — The amount of the payment intent in cents. - `amount_capturable` integer, nullable — The amount that can be captured from this PaymentIntent. - `amount_received` integer, nullable — The amount that was received in cents. - `application_fee_amount` integer, nullable — The amount of the Flex application fee. - `customer` union — An expandable field — either a string ID or an expanded Customer object. - … - `transfer_data` TransferData — Describes how funds collected by a PaymentIntent are routed to your account. Present only when the payment carries an application fee or an explicit transfer amount. - … - `status` 'canceled' | 'processing' | 'requires_action' | 'requires_capture' | 'requires_confirmation' | 'requires_payment_method' | 'succeeded', required — The current lifecycle status of the payment intent. - `latest_charge` union — An expandable field — either a string ID or an expanded Charge object. - … - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `invoice` ExpandableForInvoice — recursive - `capture_method` 'automatic' | 'automatic_async' | 'manual', required — Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time. - `client_secret` string, nullable — The client secret of the payment intent. - `metadata` object, nullable — The metadata associated with the payment intent. - `payment_method` union — An expandable field — either a string ID or an expanded PaymentMethod object. - … - `test_mode` boolean, required — Whether the payment intent is in test mode. - `transfer_group` string, nullable — A string that identifies the resulting payment as part of a group - `payment_card_type` 'primary' | 'secondary' — - `primary`: In a split cart, `Primary` refers to the HSA/FSA eligible card. In a single cart (whether it's HSA/FSA or a fully ineligible cart), `Primary` refers to the only payment card used. - `secondary`: In a split cart and partial authorization payment, `Secondary` refers to the non-eligible or backup credit card used for ineligible items. - `letter_fee_amount` integer, nullable — Letter fee portion of application_fee_amount (waterfall allocation to HSA/FSA) - `transaction_fee` integer, nullable — Transaction fee portion of application_fee_amount (percentage + fixed fee) - `last_payment_error` LastPaymentError — Structured error details from the most recent failed payment attempt on a payment intent. - … - `charge` string, nullable — The id of the latest charge for this invoice. - `customer` union — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - … - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `period_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `period_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `subscription` union — An expandable field — either a string ID or an expanded Subscription object. - string - Subscription — recursive - `paid_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `status` 'draft' | 'open' | 'void' | 'paid' | 'uncollectible', required — The lifecycle status of the invoice. - `collection_method` 'charge_automatically' | 'send_invoice', required — How payment for the invoice is collected: automatically from the customer's saved payment method, or by emailing them an invoice to pay. - `test_mode` boolean, required — Whether or not the invoice was created in test mode. - `metadata` object, nullable — Metadata associated with the invoice. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `customer` union — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - `shipping_address_id` string, required — Unique identifier for the shipping address. - `line1` string, nullable — The first line of the street address (e.g., street number and name). - `line2` string, nullable — The second line of the street address (e.g., apartment, suite, or unit). - `city` string, nullable — City, district, suburb, town, or village. - `state` string, nullable — State, county, province, or region. - `postal_code` string, nullable — ZIP or postal code. - `country` string, nullable — Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`). - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `status` 'incomplete' | 'incomplete_expired' | 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | 'paused', required — The current lifecycle status of the subscription. - `cancel_at_period_end` boolean, required — If the subscription has been canceled with the at_period_end flag set to true, cancel_at_period_end on the subscription will be true. You can use this attribute to determine whether a subscription that has a status of active is scheduled to be canceled at the end of the current period. - `current_period_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `current_period_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `metadata` object, nullable — A set of key/value pairs that you can attach to a subscription object. - `test_mode` boolean, required — Whether the subscription is in test mode. - `client_secret` SubscriptionClientSecret — Client secrets used to confirm the subscription's first payment or payment-method setup from your frontend. Present only while the subscription is being activated. - `setup_secret` string, nullable — Client secret of the SetupIntent used to collect and save a payment method for the subscription (for example, during a trial with no immediate charge). `null` when no setup is required. Do not log or store it; expose only to the customer over TLS. - `payment_secret` string, nullable — Client secret of the PaymentIntent used to confirm the subscription's first payment from your frontend. `null` when no immediate payment is required. Do not log or store it; expose only to the customer over TLS. - `proration_behavior` 'always_invoice' | 'create_prorations' | 'none' — How proration is handled when the subscription changes mid-billing-cycle. - `trial_start` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `trial_end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `cancel_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `canceled_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `default_payment_method` union — An expandable field — either a string ID or an expanded PaymentMethod object. - string - PaymentMethod — A PaymentMethod object represents a customer's payment instrument (such as a card) that can be used to collect payments. Attach it to a Customer to reuse it across checkout sessions, invoices, and subscriptions. - `payment_method_id` string, required — The ID of the PaymentMethod. - `billing_details` BillingDetails, required — Billing information associated with a PaymentMethod, such as the cardholder's billing address, email, name, and phone number. - `address` BillingAddress — A billing address attached to a PaymentMethod's billing details. - `city` string, nullable — City, district, suburb, town, or village. - `country` string, nullable — Two-letter ISO country code (e.g., `US`). - `line1` string, nullable — Address line 1, such as the street, PO box, or company name. - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building. - `postal_code` string, nullable — ZIP or postal code. - `state` string, nullable — State, county, province, or region. - `email` string, nullable — The billing email address. - `name` string, nullable — The billing name. - `phone` string, nullable — The billing phone number. - `customer` union, required — An expandable field — either a string ID or an expanded Customer object. - string - Customer — A Customer object represents a customer of your business. Use it to track payments, store reusable payment methods, and reference the customer on checkout sessions, invoices, and subscriptions. - `customer_id` string, required — The unique identifier for the customer. - `owner_partner_id` string, nullable — The partner that owns this customer. When a customer is shared with you by another partner in your organization, this is that sibling partner; otherwise it is your own partner id. - `first_name` string, required — The customer's first name. - `last_name` string, required — The customer's last name. - `email` string, email, required — The customer's email address. - `phone` string, phone, nullable — The customer's phone number. - `employer` string, nullable — The customer's employer. - `shipping` ShippingAddress — A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. - … - `metadata` object, nullable — Metadata associated with the customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the customer was created in test mode. - `metadata` object, nullable — Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. - `card` Card, required — A Card object describes the card backing a PaymentMethod, including its brand, funding type, expiration, and the last four digits. - `brand` 'american_express' | 'diners_club' | 'discover' | 'eftpos_au' | 'JCB' | 'master_card' | 'union_pay' | 'visa' | 'unknown', required — The card's network (brand). - `country` string, required — Two-letter ISO code for the card's country. - `exp_month` integer, required — The card's expiration month. - `exp_year` integer, required — The card's expiration year. - `fingerprint` string, required — Uniquely identifies this particular card number. You can use this attribute to check whether two customers who've signed up with you are using the same card. - `funding` 'credit' | 'debit' | 'hsa_fsa' | 'prepaid' | 'unknown', required — The card's funding type, such as credit, debit, prepaid, or an HSA/FSA benefits card. - `last4` string, required — The last four digits of the card. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether this PaymentMethod is in test mode. - `off_session` boolean, required — Whether this PaymentMethod is valid for off_session (customer not present) purchase flows. - `discounts` Discount[], nullable — The discounts applied to the subscription. Only present when `expand=discounts` is requested; omitted from the response otherwise. Usually 0–1 elements (Flex applies at most one coupon per subscription today), but modeled as an array for Stripe parity and future multi-discount support. Full `Discount` objects rather than `Expandable`: unlike the other expandable fields, `discounts` is populated only on `expand=discounts` and is always hydrated, so it never serializes as a bare ID. (The nested `source.coupon` inside each discount is still an `Expandable`, honoring `expand=discounts,coupons`.) - `discount_id` string, required — The ID of the discount. - `checkout_session` string, nullable — The checkout session that the discount was applied to. - `customer` string, nullable — The customer that the discount was applied to. - `subscription` string, nullable — The subscription that the discount was applied to. - `invoice` string, nullable — The invoice that the discount was applied to. - `source` DiscountSource, required — The source of a discount (coupon or promotion code). - `coupon` union, required — An expandable field — either a string ID or an expanded V1Coupon object. - string - V1Coupon — A coupon contains information about a percent-off or amount-off discount you might want to apply to a customer. Coupons may be applied to subscriptions and checkout sessions. - `coupon_id` string, required — Unique identifier for the object. - `amount_off` integer, nullable — Amount that will be taken off the subtotal of any invoices for this customer. - `applies_to` union — What a coupon's discount is restricted to. - … - `duration` 'once' | 'repeating' | 'forever', required — - `once`: Applies to the first charge from a subscription with this coupon applied. - `repeating`: Applies to charges in the first duration_in_months months from a subscription with this coupon applied. - `forever`: Applies to all charges from a subscription with this coupon applied. - `duration_in_months` integer, nullable — If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once. - `metadata` object, nullable — Set of key-value pairs 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 — Name of the coupon displayed to customers. - `percent_off` number, double, nullable — Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. - `max_redemptions` integer, nullable — Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid. - `times_redeemed` integer, nullable — Number of times this coupon has been applied to a customer. - `valid` boolean, required — Taking account of the above properties, whether this coupon can still be applied to a customer. - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `test_mode` boolean, required — Whether the coupon is in test mode - `type` 'coupon' | 'promotion_code', required — The type of discount source. - `promo_code` string, nullable — The promo code applied to create the discount. - `test_mode` boolean, required — Whether the discount was applied in test mode - `end` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). - `start` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). ## Other responses - `401` — Unauthorized - `403` — Forbidden - `404` — Not Found - `409` — Conflict - `422` — Validation Error - `429` — Too Many Requests --- [API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)