--- title: "Get Setup Intent" method: GET path: "/v1/setup_intents/{id}" tags: ["Setup Intents"] --- # Get Setup Intent `GET /v1/setup_intents/{id}` Retrieves the details of an existing SetupIntent. The response includes a fresh `client_secret` for confirming the SetupIntent from your frontend. Pass `expand=subscription` to inline the associated Subscription, when one exists. ## Path parameters - `id` string, required ## Query parameters - `expand` string — Comma-separated list of fields to expand (e.g., "subscription"). ## Response `200` SetupIntent response with expandable subscription - SetupIntentResponse — SetupIntent response with expandable subscription - `subscription` union — An expandable field — either a string ID or an expanded Subscription object. - string - Subscription — A Subscription represents a recurring billing arrangement that charges a customer at a fixed interval. It tracks the items being billed, the current billing period, its lifecycle status, and the invoices it generates each cycle. - `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. - … - `active` boolean, required — Whether the price is currently active. - `product` union, required — An expandable field — either a string ID or an expanded Product object. - … - `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`. - … - `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. - … - `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` ExpandableForSubscription — 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. - … - `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. - … - `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. - … - `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`). - `setup_intent_id` string, required — The unique identifier for the object. - `client_secret` string, nullable — The client secret used to confirm this SetupIntent from your frontend. Present when the SetupIntent is retrieved or created; `null` when it appears in a list response. Treat it as sensitive: do not log or store it, and expose it only to the customer over TLS. - `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. - `description` string, nullable — An arbitrary string attached to the setup intent. - `payment_method` string, nullable — Payment method used with this SetupIntent. - `partner_id` string, required — The ID of the account this SetupIntent belongs to. - `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. - `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 or not the setup intent is in test mode. - `status` 'requires_payment_method' | 'requires_confirmation' | 'requires_action' | 'processing' | 'succeeded' | 'canceled', required — The status of the setup intent. - `usage` 'off_session' | 'on_session', required — Whether the saved payment method is intended for off-session or on-session future payments. - `subscription_id` string, nullable — The ID of the Subscription this SetupIntent is associated with (for payment method updates). ## 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)