> ## Documentation Index > Fetch the complete documentation index at: https://docs.withflex.com/llms.txt > Use this file to discover all available pages before exploring further. # List Checkout Sessions > Returns a list of your Checkout Sessions, most recent first. ## OpenAPI ````yaml /openapi.json get /v1/checkout/sessions openapi: 3.1.0 info: title: Flex API description: >- The Flex API powers HSA/FSA payment processing for healthcare commerce: checkout sessions, payment intents, subscriptions, customers, refunds, disputes, and eligibility. Authenticate with your partner API key as a Bearer token. All endpoints are scoped to your partner account, and test mode is fully supported via test API keys. version: 0.1.0 servers: - url: https://api.withflex.com security: - BearerAuth: [] tags: - name: Balance Transactions - name: Captures - name: Checkout Sessions - name: Coupons - name: Customers - name: Disputes - name: Events - name: Exports - name: Files - name: Invoices - name: Letters - name: Orders - name: Payment Intents - name: Payment Links - name: Payouts - name: Prices - name: Products - name: Promo Codes - name: Receipts - name: Refunds - name: Setup Intents - name: Shipping Rates - name: Subscriptions paths: /v1/checkout/sessions: get: tags: - Checkout Sessions summary: List Checkout Sessions description: Returns a list of your Checkout Sessions, most recent first. operationId: v1.checkout_sessions.list parameters: - in: query name: limit description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. schema: description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. examples: - 10 type: - integer - 'null' format: int64 minimum: 1 style: form example: 10 - in: query name: offset description: Number of objects to skip before returning results. schema: description: Number of objects to skip before returning results. examples: - 3 type: - integer - 'null' format: int64 style: form example: 3 - in: query name: interval description: Filter by time interval in days (e.g., 30 for last 30 days). schema: description: Filter by time interval in days (e.g., 30 for last 30 days). examples: - 2500 type: - integer - 'null' format: int32 style: form example: 2500 - in: query name: payment_intent description: Filter by payment intent ID. schema: description: Filter by payment intent ID. examples: - fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: status description: Filter by checkout session status. schema: description: Filter by checkout session status. anyOf: - $ref: '#/components/schemas/Status' - type: 'null' style: form - in: query name: customer description: Filter by customer ID. schema: description: Filter by customer ID. examples: - fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: email description: Filter results by customer email address. schema: description: Filter results by customer email address. examples: - john.doe@example.com type: - string - 'null' format: email style: form example: john.doe@example.com - in: query name: subscription description: Filter by subscription ID. schema: description: Filter by subscription ID. examples: - fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: client_reference_id description: >- Filter by the client reference ID you provided when creating the checkout session. schema: description: >- Filter by the client reference ID you provided when creating the checkout session. examples: - example_value type: - string - 'null' style: form example: example_value - in: query name: expand_customer description: If true, expands the customer object in the response. schema: description: If true, expands the customer object in the response. examples: - false type: - boolean - 'null' style: form example: false - in: query name: expand_payment_intent description: If true, expands the payment intent object in the response. schema: description: If true, expands the payment intent object in the response. examples: - false type: - boolean - 'null' style: form example: false - in: query name: expand description: Comma-separated list of related objects to expand in the response. schema: description: Comma-separated list of related objects to expand in the response. default: '' examples: - '' type: string style: form example: '' - in: query name: created[gt] description: >- Return sessions created after this timestamp (exclusive). ISO 8601 format. schema: description: >- Return sessions created after this timestamp (exclusive). ISO 8601 format. default: null examples: - '2026-06-15T14:30:00Z' anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' style: form example: '2026-06-15T14:30:00Z' - in: query name: created[gte] description: >- Return sessions created at or after this timestamp (inclusive). ISO 8601 format. schema: description: >- Return sessions created at or after this timestamp (inclusive). ISO 8601 format. default: null examples: - '2026-06-15T14:30:00Z' anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' style: form example: '2026-06-15T14:30:00Z' - in: query name: created[lt] description: >- Return sessions created before this timestamp (exclusive). ISO 8601 format. schema: description: >- Return sessions created before this timestamp (exclusive). ISO 8601 format. default: null examples: - '2026-06-15T14:30:00Z' anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' style: form example: '2026-06-15T14:30:00Z' - in: query name: created[lte] description: >- Return sessions created at or before this timestamp (inclusive). ISO 8601 format. schema: description: >- Return sessions created at or before this timestamp (inclusive). ISO 8601 format. default: null examples: - '2026-06-15T14:30:00Z' anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' style: form example: '2026-06-15T14:30:00Z' - in: query name: starting_after description: >- A cursor for use in pagination. `starting_after` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, ending with `fcs_xyz`, your subsequent call can include `starting_after=fcs_xyz` to fetch the next page. schema: description: >- A cursor for use in pagination. `starting_after` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, ending with `fcs_xyz`, your subsequent call can include `starting_after=fcs_xyz` to fetch the next page. examples: - fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: ending_before description: >- A cursor for use in pagination. `ending_before` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, starting with `fcs_abc`, your subsequent call can include `ending_before=fcs_abc` to fetch the previous page. schema: description: >- A cursor for use in pagination. `ending_before` is a checkout session ID that defines your place in the list. For instance, if you make a list request and receive 20 checkout sessions, starting with `fcs_abc`, your subsequent call can include `ending_before=fcs_abc` to fetch the previous page. examples: - fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: has_disputes description: Return only checkout sessions with any associated dispute schema: description: Return only checkout sessions with any associated dispute examples: - false type: - boolean - 'null' style: form example: false responses: '200': description: Success content: application/json: schema: $ref: >- #/components/schemas/MultipleCheckoutSessionBody_for_CheckoutSession example: checkout_sessions: - allow_promotion_codes: false amount_total: 2500 amount_subtotal: 2500 amount_received: 2500 amount_refunded: 2500 amount_disputed: 2500 cancel_url: https://example.com captures: [] disputes: [] capture_method: automatic checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: example_value created_at: 2500 expires_at: 2500 invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA hsa_fsa_eligible: false letter_of_medical_necessity_required: false metadata: order_id: '8842' channel: shopify mode: payment redirect_url: https://example.com refunds: [] setup_intent: fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_address_collection: false status: open success_url: https://example.com fees: [] test_mode: false total_details: {} setup_future_use: on_session '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' example: detail: - loc: - string msg: string type: string '429': description: Too Many Requests content: application/json: schema: $ref: '#/components/schemas/HttpErrorOut' example: code: string detail: string security: - BearerAuth: - checkout_sessions:read components: schemas: Status: description: The status of the checkout session. type: string enum: - open - paid - complete - canceled - expired example: open Timestamptz: description: >- A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). type: string example: string MultipleCheckoutSessionBody_for_CheckoutSession: description: An envelope wrapping a list of checkout session objects. type: object required: - checkout_sessions properties: checkout_sessions: description: The list of checkout sessions. type: array items: $ref: '#/components/schemas/CheckoutSession' example: checkout_sessions: - allow_promotion_codes: false amount_total: 2500 amount_subtotal: 2500 amount_received: 2500 amount_refunded: 2500 amount_disputed: 2500 cancel_url: https://example.com captures: [] disputes: [] capture_method: automatic checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: example_value created_at: 2500 expires_at: 2500 invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA hsa_fsa_eligible: false letter_of_medical_necessity_required: false metadata: order_id: '8842' channel: shopify mode: payment redirect_url: https://example.com refunds: [] setup_intent: fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_address_collection: false status: open success_url: https://example.com fees: [] test_mode: false total_details: {} setup_future_use: on_session HttpErrorOut: title: HttpError description: The error response returned when a request cannot be completed. type: object required: - code - detail properties: code: description: A short machine-readable error code identifying the type of error. type: string detail: description: A human-readable explanation of what went wrong. type: string example: code: string detail: string HTTPValidationError: description: The error response returned when request validation fails (HTTP 422). type: object required: - detail properties: detail: description: The list of validation errors, one entry per invalid field. type: array items: $ref: '#/components/schemas/ValidationErrorItem' example: detail: - loc: - string msg: string type: string CheckoutSession: description: >- A Checkout Session represents a customer's session as they pay for one-time purchases or subscriptions through Flex's hosted checkout page. Create one to obtain a hosted `redirect_url`, then capture, refund, or reconcile the resulting payments. For HSA/FSA purchases the session also drives eligibility classification and, when required, collection of a Letter of Medical Necessity (LOMN). type: object required: - allow_promotion_codes - amount_subtotal - amount_total - capture_method - captures - checkout_session_id - created_at - expires_at - hsa_fsa_eligible - letter_of_medical_necessity_required - mode - redirect_url - refunds - shipping_address_collection - status - success_url - test_mode - total_details properties: allow_promotion_codes: description: Whether promotion codes can be applied to the checkout session. type: boolean example: false amount_total: description: The total amount of the checkout session. type: integer format: int32 example: 2500 amount_subtotal: description: The subtotal amount of the checkout session. type: integer format: int32 example: 2500 amount_received: description: The amount actually received from payment intents. type: - integer - 'null' format: int32 example: 2500 amount_refunded: description: The total amount refunded for this checkout session. type: - integer - 'null' format: int32 example: 2500 amount_disputed: description: >- The total amount currently in dispute for this checkout session. Includes all dispute statuses except Won and Prevented. type: - integer - 'null' format: int32 example: 2500 cancel_url: description: >- If set, Checkout displays a back button and customers will be directed to this URL if they decide to cancel payment and return to your website. type: - string - 'null' example: https://example.com captures: description: A list of captures associated with the checkout session. type: array items: $ref: '#/components/schemas/Expandable_for_V1Capture' disputes: description: Disputes associated with this checkout session's payment intents. default: [] type: array items: $ref: '#/components/schemas/Expandable_for_Dispute' capture_method: $ref: '#/components/schemas/PaymentIntentCaptureMethod' description: >- Controls when funds are captured from the customer's account. One of `automatic` or `automatic_async` (capture immediately when the customer pays), or `manual` (authorize the payment and require a later capture via the capture endpoint). checkout_session_id: description: The ID of the Checkout Session. type: string example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: description: >- A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems. type: - string - 'null' example: example_value created_at: description: >- Time at which the Checkout Session was created, as a Unix timestamp in seconds. type: integer format: int64 example: 2500 customer: description: >- The ID of the customer for this Session. This object is expandable if expand_customer is set. anyOf: - $ref: '#/components/schemas/Expandable_for_Customer' - type: 'null' defaults: description: >- The customer values to prefill the customer details in the checkout page. anyOf: - $ref: '#/components/schemas/CustomerDefaults' - type: 'null' expires_at: description: The time at which the Checkout Session will expire. type: integer format: int64 example: 2500 invoice: description: The ID of the invoice this Checkout Session is for, if any. type: - string - 'null' example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA hsa_fsa_eligible: description: Whether the Checkout Session is HSA/FSA eligible. type: boolean example: false letter_of_medical_necessity_required: description: >- Whether a letter of medical necessity is required for this Checkout Session. type: boolean example: false metadata: description: Metadata to attach to the Checkout Session. type: - object - 'null' example: order_id: '8842' channel: shopify mode: $ref: '#/components/schemas/Mode' description: The mode of the Checkout Session. origin: description: >- Where the Checkout Session was generated. `null` for sessions created directly via the API. anyOf: - $ref: '#/components/schemas/CheckoutSessionOrigin' - type: 'null' payment_intent: description: >- The payment intent that belongs to this Checkout Session. This object is expandable if expand_payment_intent is set. anyOf: - $ref: '#/components/schemas/Expandable_for_PaymentIntent' - type: 'null' payment_intents: description: >- All payment intents that belong to this Checkout Session. Each is expandable if expand_payment_intent is set. type: - array - 'null' items: $ref: '#/components/schemas/Expandable_for_PaymentIntent' redirect_url: description: The URL to redirect to access the checkout session. type: string format: uri example: https://example.com refunds: description: The refunds associated with this Checkout Session. type: array items: $ref: '#/components/schemas/Expandable_for_Refund' setup_intent: description: The ID of the SetupIntent for this Checkout Session, if any. type: - string - 'null' example: fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_options: description: The shipping rate options applied to this Session. anyOf: - $ref: '#/components/schemas/ShippingRateOptions' - type: 'null' shipping_address_collection: description: >- When set, present options for shipping address collection from a customer. type: boolean example: false shipping_details: description: Shipping information for this Checkout Session. anyOf: - $ref: '#/components/schemas/ShippingAddress' - type: 'null' split_cart: description: >- If this checkout session contains both items that are eligible for HSA/FSA and items that are not, This will be the ID of the split cart object. This object is expandable if expand_split_cart is set. anyOf: - $ref: '#/components/schemas/Expandable_for_SplitCart' - type: 'null' status: $ref: '#/components/schemas/Status' description: The status of the checkout session. success_url: description: >- The URL the customer will be directed to after the payment or subscription creation is successful. type: string example: https://example.com fees: description: The fees associated with this Checkout Session. default: [] type: array items: $ref: '#/components/schemas/V1Fee' custom_text: description: Custom text displayed to customers during checkout anyOf: - $ref: '#/components/schemas/CustomText' - type: 'null' subscription: description: >- The ID of the subscription this Checkout Session is for. This object is expandable if expand_subscription is set. anyOf: - $ref: '#/components/schemas/Expandable_for_Subscription' - type: 'null' subscription_data: description: >- The data that will be used to create a subscription. Populated by default on single-session endpoints (create / retrieve / update) when a subscription_data row exists — no `expand` required. List endpoints omit this field to avoid an extra per-row query. anyOf: - $ref: '#/components/schemas/V1SubscriptionData' - type: 'null' tax_rate: description: The tax rate for the checkout session. anyOf: - $ref: '#/components/schemas/TaxRate' - type: 'null' tax_calculation_mode: description: >- If Flex is calculating the tax, this specifies whether it should be calculated inclusive or exclusive. 'None' means that Flex will not calculate the tax, and the merchant must pass it in as a TaxRate if they want it included. anyOf: - $ref: '#/components/schemas/TaxCalculationMode' - type: 'null' test_mode: description: Whether the Checkout Session is in test mode. type: boolean example: false total_details: $ref: '#/components/schemas/TotalDetails' description: Tax and discount details for the computed total amount. visit_type: description: The type of visit this Checkout Session is for. anyOf: - $ref: '#/components/schemas/VisitTypeName' - type: 'null' setup_future_use: $ref: '#/components/schemas/FutureUse' description: >- How this checkout session enables the payment methods to be used in the future default: on_session payment_method_options: description: Payment method-specific options for this checkout session. anyOf: - $ref: '#/components/schemas/PaymentMethodOptions' - type: 'null' next_action: description: >- If present, indicates an action the merchant must take to complete the checkout. Currently used when a Letter of Medical Necessity is required for an off-session payment. anyOf: - $ref: '#/components/schemas/NextAction' - type: 'null' partner: description: >- Your account. Returned as its ID by default; expandable to the full `partner` object when `partner` is expanded. anyOf: - $ref: '#/components/schemas/Expandable_for_PartnerMetadata' - type: 'null' platform_fees: description: >- Platform fees charged on this checkout. Present only for checkouts on the deferred-collection feature whose status is `complete`. Omitted otherwise. anyOf: - $ref: '#/components/schemas/PlatformFees' - type: 'null' example: allow_promotion_codes: false amount_total: 2500 amount_subtotal: 2500 amount_received: 2500 amount_refunded: 2500 amount_disputed: 2500 cancel_url: https://example.com captures: - fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA disputes: - fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA capture_method: automatic checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: example_value created_at: 2500 customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA defaults: customer_id: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA email: john.doe@example.com first_name: John last_name: Doe phone: '+14155550142' expires_at: 2500 invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA hsa_fsa_eligible: false letter_of_medical_necessity_required: false metadata: order_id: '8842' channel: shopify mode: payment origin: shopify payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA redirect_url: https://example.com refunds: - fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA setup_intent: fseti_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_options: shipping_rate_id: fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_amount: 2500 display_name: Example shipping_address_collection: false shipping_details: shipping_address_id: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US split_cart: fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: open success_url: https://example.com fees: - fee_id: ffee_1234567890 amount: 2500 name: Example description: Premium SPF 50 mineral sunscreen fee_type: lmn_consultation custom_text: {} subscription: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA subscription_data: cancel_at: '2026-06-15T14:30:00Z' cancel_at_period_end: false tax_rate: amount: 2500 tax_calculation_mode: exclusive test_mode: false total_details: amount_discount: 2500 amount_tax: 2500 amount_shipping: 2500 amount_iias: 2500 amount_vision: 2500 amount_prescription: 2500 amount_service: 2500 amount_fee: 2500 breakdown: {} visit_type: cbtSleep setup_future_use: on_session payment_method_options: {} next_action: type: collect_letter_of_medical_necessity partner: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA platform_fees: letter_fee: {} ValidationErrorItem: description: >- Validation errors have their own schema to provide context for invalid requests eg. mismatched types and out of bounds values. There may be any number of these per 422 UNPROCESSABLE ENTITY error. type: object required: - loc - msg - type properties: loc: description: >- The location as a [`Vec`] of [`String`]s -- often in the form `["body", "field_name"]`, `["query", "field_name"]`, etc. They may, however, be arbitarily deep. type: array items: type: string msg: description: The message accompanying the validation error item. type: string type: description: >- The type of error, often "type_error" or "value_error", but sometimes with more context like as "value_error.number.not_ge" type: string example: loc: - string msg: string type: string Expandable_for_V1Capture: anyOf: - type: string example: fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/V1Capture' example: fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded V1Capture object. Expandable_for_Dispute: anyOf: - type: string example: fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Dispute' example: fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded Dispute object. PaymentIntentCaptureMethod: description: >- Controls when funds are captured: automatically once the payment is confirmed, or manually at a later time. type: string enum: - automatic - automatic_async - manual example: automatic Expandable_for_Customer: anyOf: - type: string example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Customer' example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded Customer object. CustomerDefaults: description: >- Customer values used to prefill the customer details on the hosted checkout page. type: object properties: customer_id: description: >- ID of an existing Customer to associate with the session. When set, the customer's saved details are used instead of the other fields. type: - string - 'null' example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA email: description: The customer's email address, prefilled on the checkout page. type: - string - 'null' example: john.doe@example.com first_name: description: The customer's first name, prefilled on the checkout page. type: - string - 'null' example: John last_name: description: The customer's last name, prefilled on the checkout page. type: - string - 'null' example: Doe phone: description: >- The customer's phone number in E.164 format, prefilled on the checkout page. type: - string - 'null' example: '+14155550142' example: customer_id: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA email: john.doe@example.com first_name: John last_name: Doe phone: '+14155550142' Mode: description: >- The mode of the checkout session, which determines what happens on completion: a one-time payment, starting a subscription, charging a saved payment method off-session, or saving a payment method for future use. type: string enum: - payment - subscription - off_session - setup example: payment CheckoutSessionOrigin: description: Origin of where the checkout session was generated type: string enum: - shopify - shopline - prepurchase - postpurchase example: shopify Expandable_for_PaymentIntent: example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA anyOf: - type: string example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/PaymentIntent' description: >- An expandable field — either a string ID or an expanded PaymentIntent object. Expandable_for_Refund: anyOf: - type: string example: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Refund' example: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded Refund object. ShippingRateOptions: description: >- A resolved shipping option attached to a checkout session or payment link, capturing the applied shipping rate and its cost. type: object required: - shipping_amount - shipping_rate_id properties: shipping_rate_id: description: ID of the applied shipping rate. type: string example: fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_amount: description: >- The shipping cost, in the smallest currency unit (e.g., `500` = $5.00 USD). Charged in USD. type: integer format: int32 example: 2500 display_name: description: >- The display name of the shipping rate (e.g., "Standard Shipping", "Express"). type: - string - 'null' example: Example example: shipping_rate_id: fshr_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_amount: 2500 display_name: Example ShippingAddress: description: >- A ShippingAddress represents the postal address a physical order is delivered to. It is referenced by checkout sessions and customers. type: object required: - shipping_address_id properties: shipping_address_id: description: Unique identifier for the shipping address. type: string example: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: description: The first line of the street address (e.g., street number and name). type: - string - 'null' example: 123 Main St line2: description: >- The second line of the street address (e.g., apartment, suite, or unit). type: - string - 'null' example: Suite 100 city: description: City, district, suburb, town, or village. type: - string - 'null' example: San Francisco state: description: State, county, province, or region. type: - string - 'null' example: CA postal_code: description: ZIP or postal code. type: - string - 'null' example: '94107' country: description: Two-letter country code (ISO 3166-1 alpha-2, e.g., `US`). type: - string - 'null' example: US example: shipping_address_id: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US Expandable_for_SplitCart: anyOf: - type: string example: fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/SplitCart' example: fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded SplitCart object. V1Fee: description: A simplified representation of a fee for API responses type: object required: - amount - fee_id - fee_type properties: fee_id: description: Unique identifier for the fee. type: string example: ffee_1234567890 amount: description: The amount of the fee in cents. type: integer format: int32 example: 2500 name: description: The name of the fee. type: - string - 'null' example: Example description: description: The description of the fee. type: - string - 'null' example: Premium SPF 50 mineral sunscreen fee_type: $ref: '#/components/schemas/FeeType' description: The type of the fee. applied: description: Whether the fee was applied to the checkout session. type: - boolean - 'null' example: fee_id: ffee_1234567890 amount: 2500 name: Example description: Premium SPF 50 mineral sunscreen fee_type: lmn_consultation CustomText: description: Custom text displayed to customers in checkout UI type: object properties: after_submit: description: Text shown after payment submission anyOf: - $ref: '#/components/schemas/CustomTextMessage' - type: 'null' shipping_address: description: Text shown in shipping address collection anyOf: - $ref: '#/components/schemas/CustomTextMessage' - type: 'null' submit: description: Text shown near submit button anyOf: - $ref: '#/components/schemas/CustomTextMessage' - type: 'null' terms_of_service_acceptance: description: Text shown for terms of service acceptance anyOf: - $ref: '#/components/schemas/CustomTextMessage' - type: 'null' terms_of_service_checkbox_required: description: >- Whether the terms of service acceptance checkbox must be shown and checked type: - boolean - 'null' payment: description: Text shown in payment section anyOf: - $ref: '#/components/schemas/CustomTextMessage' - type: 'null' example: after_submit: message: Premium SPF 50 mineral sunscreen shipping_address: message: Premium SPF 50 mineral sunscreen submit: message: Premium SPF 50 mineral sunscreen terms_of_service_acceptance: message: Premium SPF 50 mineral sunscreen payment: message: Premium SPF 50 mineral sunscreen Expandable_for_Subscription: example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA anyOf: - type: string example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Subscription' description: >- An expandable field — either a string ID or an expanded Subscription object. V1SubscriptionData: description: >- Subscription Data holds the trial and cancellation settings to apply to the subscription that a checkout session creates once payment completes. type: object properties: cancel_at: description: >- A future RFC 3339 timestamp at which the created subscription will automatically be canceled. `null` if no future cancellation is scheduled. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' trial_end: description: >- RFC 3339 timestamp at which the trial period ends for the created subscription. `null` if no trial end was set on the checkout session. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' cancel_at_period_end: description: >- Whether the created subscription will cancel at the end of its current billing period rather than renewing. type: - boolean - 'null' example: false trial_period_days: description: >- Length of the trial period, in days, for the created subscription. `null` if no day-based trial was set on the checkout session. type: - integer - 'null' format: int32 example: cancel_at: '2026-06-15T14:30:00Z' trial_end: string cancel_at_period_end: false TaxRate: description: >- A fixed tax amount to apply to a Checkout Session or line item. Use this to pass a tax figure you have calculated yourself, rather than having Flex compute it. type: object required: - amount properties: amount: description: >- The tax amount to apply, in the smallest currency unit (e.g., `175` = $1.75 USD). type: integer format: int32 example: 2500 example: amount: 2500 TaxCalculationMode: description: >- Whether tax should be calculated exclusive or inclusive of the provided total type: string enum: - exclusive - inclusive example: exclusive TotalDetails: description: Tax and discount details for the computed total amount. type: object properties: amount_discount: description: This is the sum of all the discount amounts. type: - integer - 'null' format: int32 example: 2500 amount_tax: description: This is the sum of all the tax amounts. type: - integer - 'null' format: int32 example: 2500 amount_shipping: description: This is the sum of all the shipping amounts. type: - integer - 'null' format: int32 example: 2500 amount_iias: description: This is the sum of all the iias line items. type: - integer - 'null' format: int32 example: 2500 amount_vision: description: >- Sum of the line item amounts classified as vision care, in the smallest currency unit (e.g., `2500` = $25.00 USD). `null` when no vision items are present. type: - integer - 'null' format: int32 example: 2500 amount_prescription: description: >- Sum of the line item amounts classified as prescription, in the smallest currency unit (e.g., `3000` = $30.00 USD). `null` when no prescription items are present. type: - integer - 'null' format: int32 example: 2500 amount_service: description: >- Sum of the line item amounts classified as a medical service, in the smallest currency unit (e.g., `5000` = $50.00 USD). `null` when no service items are present. type: - integer - 'null' format: int32 example: 2500 amount_fee: description: This is the sum of all the fee amounts. type: - integer - 'null' format: int32 example: 2500 breakdown: description: Breakdown of the components that make up the total details. anyOf: - $ref: '#/components/schemas/Breakdown' - type: 'null' example: amount_discount: 2500 amount_tax: 2500 amount_shipping: 2500 amount_iias: 2500 amount_vision: 2500 amount_prescription: 2500 amount_service: 2500 amount_fee: 2500 breakdown: discounts: [] VisitTypeName: description: The name of the telehealth visit type. type: string enum: - cbtSleep - notApplicable - metabolomics - tinnitus - gym - exerciseDiet - orthopedic - alcohol - airPurification - vaginalHealth - menstrual - canopy - alopecia - genate - weightBlanket - bedJet - siderAl - sunwinkPowder - wavWatch - bodyComplete - ageRate - nitrousOxide - happyV - groupChat - icalmAnxiety - redBloom - foodom - branchErgonomicFurniture - curalife - eloraInfantWellness - nutriHealth - olipop - goldIntimate - touchStoneEssentials - utiva - sleepGeekz - figBrew - auBabyBlanket - babySleepSack - oshWellness - currentBodyRedLight - mito - circularRing - lymaRedLight - goodAirRx - tastermonial - karunaHome - ergoStandingChair - jbaGlucoseControl - bloomNutrition - buoyDrops - luxeWonderWig - saunaMarketplace - amrioreEyewear - pivotOrthoShoe - lumenCynergy - roga - pulsetto - mitoRedLight - gutPersonal - goFlaus - myHixel - calmigo - dotFit - stripesBeauty - mixHers - pmd - positivityWithPurpose - techRing - popVeneers - vertaClean - lumen - medicalMeal - emnHealth - detergentAllergy - lowImpactExercise - mediumImpactExercise - highImpactExercise - gardening - babyCarrier - coolingBed - posture - supplements - sleep - redLightTherapy - fitness - smartRing - womensVaginalHealth - fertilitySupport - femaleReproduction - femaleReproductionFood - pregnancyLiterature - iceBath - orthopedicShoes - sexualHealth - glucose - metabolicTest - skinCare - oralHealth - oralAnxiety - blueLightGlasses - anxiety - brainHealth - babyMonitor - compressionSocks - compressionShorts - waterPurification - medSpa - essentialOils - sleepBuds - latchLight - nutritionist - rairflow - enduranceTraining - hydration - hairGrowth - eD - postureFitness - childDevelopment - adaptiveClothing - adaptiveShoes - sleepConsulting - hairRemoval - menopause - maleFertility - anxietyHealth - bidets - speechHealth - smartGlasses - artOfLiving - breastMilk - breathWork - petSupport - diapers - gutSupplements - smartWatch - medicalBotox - biomechanicalAssessment - erectileReset - femaleOrgasm - pornAddiction - oralHealthMasticGum example: cbtSleep FutureUse: type: string enum: - on_session - off_session x-ms-enum: name: FutureUse modelAsString: false values: - value: on_session name: OnSession description: Standard payments requiring customer auth - value: off_session name: OffSession description: Allows payments without the customer present in the flow description: >- - `on_session`: Standard payments requiring customer auth - `off_session`: Allows payments without the customer present in the flow example: on_session PaymentMethodOptions: description: Payment method-specific options applied to a Checkout Session. type: object properties: card: description: >- Options that apply to card payments. `null` when no card-specific options are set. anyOf: - $ref: '#/components/schemas/CardPaymentMethodOptions' - type: 'null' example: card: request_three_d_secure: automatic NextAction: description: >- Represents an action required to complete the checkout. The `type` field indicates which action is needed, and the corresponding nested object contains the action-specific data. example: type: collect_letter_of_medical_necessity collect_letter_of_medical_necessity: url: https://example.com type: object properties: type: type: string enum: - collect_letter_of_medical_necessity - payment_failed - provide_second_payment_method - provide_alternative_payment_method collect_letter_of_medical_necessity: $ref: '#/components/schemas/CollectLetterOfMedicalNecessityAction' description: Redirect the customer to collect a Letter of Medical Necessity payment_failed: $ref: '#/components/schemas/PaymentFailedAction' description: >- Payment failed during off-session checkout (e.g., card declined, insufficient funds) provide_second_payment_method: $ref: '#/components/schemas/ProvideSecondPaymentMethodAction' description: >- A second payment method is required for a split cart off-session checkout provide_alternative_payment_method: $ref: '#/components/schemas/ProvideAlternativePaymentMethodAction' description: >- An alternative payment method is required because the provided payment method cannot be used to complete the transaction. required: - type Expandable_for_PartnerMetadata: anyOf: - type: string example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/PartnerMetadata' example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded PartnerMetadata object. PlatformFees: description: >- Platform fees charged on a checkout session. Present only when you are on the deferred-collection feature and the checkout has completed. type: object required: - letter_fee properties: letter_fee: $ref: '#/components/schemas/LetterFee' description: The Letter of Medical Necessity fee charged on this checkout. example: letter_fee: amount: 2500 status: pending V1Capture: description: >- A capture represents a charge that has been captured from a customer's account. You can capture a charge in full or in part. type: object required: - amount_captured - capture_id - created_at - items - test_mode properties: amount_captured: description: The total amount captured from the capture request type: integer format: int32 example: 2500 amount_shipping_captured: description: The shipping amount captured type: - integer - 'null' format: int32 example: 2500 amount_discount_captured: description: The discount amount captured type: - integer - 'null' format: int32 example: 2500 amount_tax_captured: description: The tax amount captured type: - integer - 'null' format: int32 example: 2500 capture_id: description: The unique identifier for the capture. type: string example: fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: $ref: '#/components/schemas/Timestamptz' description: The created at timestamp for the capture example: '2026-06-15T14:30:00Z' items: description: The items associated with the capture type: array items: $ref: '#/components/schemas/V1CaptureItem' metadata: description: Metadata associated with the capture type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify test_mode: description: Whether the capture is in test mode type: boolean example: false example: amount_captured: 2500 amount_shipping_captured: 2500 amount_discount_captured: 2500 amount_tax_captured: 2500 capture_id: fcap_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' items: - amount_captured: 2500 capture_item_id: fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false metadata: order_id: '8842' channel: shopify test_mode: false Dispute: description: >- A Dispute object represents a customer's challenge to a payment, raised through their card issuer or bank (also known as a chargeback). Use it to track the dispute's status, review the reason it was filed, and submit evidence to contest it. type: object required: - amount - created_at - currency - dispute_id - is_charge_refundable - metadata - payment_intent_id - reason - status - test_mode properties: dispute_id: description: Unique identifier for the dispute, prefixed with `fdp_`. type: string example: fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: description: ID of the PaymentIntent that was disputed. type: string example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: >- Disputed amount, in the smallest currency unit (e.g., `2500` = $25.00 USD). Usually the full amount of the disputed payment. type: integer format: int32 example: 2500 currency: description: Three-letter ISO currency code, in lowercase (e.g., `usd`). type: string example: usd charge_id: description: >- ID of the Charge that was disputed. `null` if the originating charge could not be resolved. type: - string - 'null' example: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: description: >- Set of key-value pairs attached to the dispute for storing additional structured information. type: object example: order_id: '8842' channel: shopify created_at: $ref: '#/components/schemas/Timestamptz' description: >- Time at which the dispute was created, as an RFC 3339 date-time string. example: '2026-06-15T14:30:00Z' status: $ref: '#/components/schemas/DisputeStatus' description: >- The current status of the dispute. Evidence can only be submitted while the status is `needs_response` or `warning_needs_response`. reason: $ref: '#/components/schemas/DisputeReason' description: Reason the dispute was filed, as reported by the card network. is_charge_refundable: description: >- Whether the disputed charge can still be refunded. Once a payment is disputed, refunding it is typically no longer possible. type: boolean example: false evidence: description: >- Evidence collected to respond to the dispute. On the list endpoint this is included only when you pass `expand=evidence`; `null` when no evidence has been recorded. anyOf: - $ref: '#/components/schemas/DisputeEvidenceResponse' - type: 'null' evidence_details: description: >- Metadata about the evidence submission, including the response deadline and whether evidence has been submitted. anyOf: - $ref: '#/components/schemas/EvidenceDetails' - type: 'null' balance_transactions: description: >- Balance transactions that record the funds withdrawn and returned as the dispute progresses (e.g., the initial debit and any reversal). An empty array when there are none. type: - array - 'null' items: $ref: '#/components/schemas/DisputeBalanceTransactionInfo' payment_method_details: description: >- Details of the payment method that was disputed, such as the card brand and network reason code. `null` when no payment method details are available. anyOf: - $ref: '#/components/schemas/DisputePaymentMethodDetails' - type: 'null' test_mode: description: >- Whether the dispute was created in test mode. `true` for disputes created with test API keys. type: boolean example: false client_reference_id: description: >- Your own identifier for the customer or payment this dispute relates to, copied from the originating payment. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA example: dispute_id: fdp_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 currency: usd charge_id: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' status: lost reason: bank_cannot_process is_charge_refundable: false evidence: {} evidence_details: due_by: '2026-06-15T14:30:00Z' has_evidence: false past_due: false submission_count: 3 payment_method_details: type: string test_mode: false client_reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA Customer: description: >- 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. type: object required: - created_at - customer_id - email - first_name - last_name - test_mode properties: customer_id: description: The unique identifier for the customer. type: string example: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: description: >- 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. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: description: The customer's first name. type: string example: John last_name: description: The customer's last name. type: string example: Doe email: description: The customer's email address. type: string format: email example: joh.doe@example.com phone: description: The customer's phone number. type: - string - 'null' format: phone example: '+15555555555' employer: description: The customer's employer. type: - string - 'null' example: Flex shipping: description: The customer's shipping address. anyOf: - $ref: '#/components/schemas/ShippingAddress' - type: 'null' metadata: description: Metadata associated with the customer. type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify created_at: $ref: '#/components/schemas/Timestamptz' description: The time the customer was created. example: '2026-06-15T14:30:00Z' test_mode: description: Whether the customer was created in test mode. type: boolean example: false example: customer_id: fcus_01HACM7FZ1084XB1GB6053VM0D owner_partner_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA first_name: John last_name: Doe email: joh.doe@example.com phone: '+15555555555' employer: Flex shipping: shipping_address_id: fsh_01J9XR8M3K7VZ8N2YB4WJ6T0RA line1: 123 Main St line2: Suite 100 city: San Francisco state: CA postal_code: '94107' country: US metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' test_mode: false PaymentIntent: description: >- 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`. type: object required: - amount - capture_method - created_at - payment_intent_id - status - test_mode properties: payment_intent_id: description: The unique identifier for the payment intent. type: string example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: The amount of the payment intent in cents. type: integer format: int32 example: 2500 amount_capturable: description: The amount that can be captured from this PaymentIntent. type: - integer - 'null' format: int32 example: 2500 amount_received: description: The amount that was received in cents. type: - integer - 'null' format: int32 example: 2500 application_fee_amount: description: The amount of the Flex application fee. type: - integer - 'null' format: int32 customer: description: The customer associated with the payment intent. anyOf: - $ref: '#/components/schemas/Expandable_for_Customer' - type: 'null' transfer_data: description: The data related to the amount being transferred. anyOf: - $ref: '#/components/schemas/TransferData' - type: 'null' status: $ref: '#/components/schemas/PaymentIntentStatus' description: The status of the payment intent. latest_charge: description: The latest charge associated with the payment intent. anyOf: - $ref: '#/components/schemas/Expandable_for_Charge' - type: 'null' created_at: $ref: '#/components/schemas/Timestamptz' description: The time the payment intent was created. example: '2026-06-15T14:30:00Z' invoice: description: The invoice associated with the payment intent. anyOf: - $ref: '#/components/schemas/Expandable_for_Invoice' - type: 'null' capture_method: $ref: '#/components/schemas/PaymentIntentCaptureMethod' description: The capture method of the payment intent. client_secret: description: The client secret of the payment intent. type: - string - 'null' metadata: description: The metadata associated with the payment intent. type: - object - 'null' example: order_id: '8842' channel: shopify payment_method: description: The payment method associated with the payment intent. anyOf: - $ref: '#/components/schemas/Expandable_for_PaymentMethod' - type: 'null' test_mode: description: Whether the payment intent is in test mode. type: boolean example: false transfer_group: description: A string that identifies the resulting payment as part of a group type: - string - 'null' example: example_value payment_card_type: description: The primary card type used for this payment intent anyOf: - $ref: '#/components/schemas/PaymentCardType' - type: 'null' letter_fee_amount: description: >- Letter fee portion of application_fee_amount (waterfall allocation to HSA/FSA) type: - integer - 'null' format: int32 transaction_fee: description: >- Transaction fee portion of application_fee_amount (percentage + fixed fee) type: - integer - 'null' format: int32 last_payment_error: description: The error from the most recent failed payment attempt, if any. anyOf: - $ref: '#/components/schemas/LastPaymentError' - type: 'null' example: payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 amount_capturable: 2500 amount_received: 2500 customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA transfer_data: amount: 2500 destination: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: canceled latest_charge: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA capture_method: automatic metadata: order_id: '8842' channel: shopify payment_method: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false transfer_group: example_value payment_card_type: primary last_payment_error: type: string payment_method: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA Refund: description: >- A Refund object represents the return of funds for a previously succeeded payment, in whole or in part. Issuing a refund reverses the corresponding charge(s) on the customer's HSA/FSA and/or credit card payment methods. type: object required: - amount - created_at - refund_id - status - test_mode properties: refund_id: description: The ID of the refund type: string example: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: description: The ID of the payment intent that the refund is associated with type: - string - 'null' example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: The amount of the refund in cents type: integer format: int32 example: 2500 created_at: $ref: '#/components/schemas/Timestamptz' description: The time at which the refund was created. ISO 8601 format. example: '2026-06-15T14:30:00Z' reason: description: The reason for the refund anyOf: - $ref: '#/components/schemas/RefundReason' - type: 'null' status: $ref: '#/components/schemas/RefundStatus' description: The status of the refund test_mode: description: Whether the refund was created in test mode type: boolean example: false metadata: description: Metadata attached to the refund type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify reference_id: description: >- Reference number that the customer can use to trace this refund with their bank or card issuer. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: description: Type of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceType' - type: 'null' reference_status: description: Status of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceStatus' - type: 'null' items: description: List of refund items (charges that were refunded) default: [] type: array items: $ref: '#/components/schemas/RefundItem' subscription_id: description: >- The subscription this refund is associated with (for subscription cancellation refunds) type: - string - 'null' example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice_id: description: >- The invoice this refund is associated with (for subscription billing period refunds) type: - string - 'null' example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA balance_transaction: description: >- Balance transaction that describes the impact of this refund on your balance. Defaults to the balance transaction ID; use `?expand=balance_transaction` to inflate the full object. anyOf: - $ref: '#/components/schemas/Expandable_for_BalanceTransaction' - type: 'null' failure_balance_transaction: description: >- After a refund fails, the balance transaction describing the adjustment that returns the funds to your balance. anyOf: - $ref: '#/components/schemas/Expandable_for_BalanceTransaction' - type: 'null' example: refund_id: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 created_at: '2026-06-15T14:30:00Z' reason: duplicate status: pending test_mode: false metadata: order_id: '8842' channel: shopify reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: acquirer_reference_number reference_status: available items: - amount_refunded: 2500 payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_method_id: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA subscription_id: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice_id: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA balance_transaction: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA failure_balance_transaction: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA SplitCart: description: >- A SplitCart represents a checkout session whose items are divided into two separate payments: one for HSA/FSA-eligible items and one for non-eligible items. It is created automatically when a session mixes eligible and ineligible products, so the customer can pay for the eligible portion with their HSA/FSA card. type: object required: - eligible_cart - non_eligible_cart - split_cart_id properties: split_cart_id: description: Unique identifier for the split cart. type: string example: fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA eligible_cart: $ref: '#/components/schemas/Cart' description: >- The portion of the cart containing HSA/FSA-eligible items, charged to the customer's HSA/FSA payment method. non_eligible_cart: $ref: '#/components/schemas/Cart' description: >- The portion of the cart containing non-eligible items, charged to the customer's standard payment method. checkout_session_id: description: >- ID of the Checkout Session this split cart belongs to. `null` until the split cart has been associated with a session. type: - string - 'null' example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA example: split_cart_id: fsplit_01J9XR8M3K7VZ8N2YB4WJ6T0RA eligible_cart: amount_total: 2500 amount_subtotal: 2500 amount_tax: 2500 amount_discount: 2500 amount_shipping: 2500 non_eligible_cart: amount_total: 2500 amount_subtotal: 2500 amount_tax: 2500 amount_discount: 2500 amount_shipping: 2500 checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA FeeType: description: >- The kind of fee applied to a checkout session: a Letter of Medical Necessity consultation fee, or a custom fee you define. type: string enum: - lmn_consultation - custom example: lmn_consultation CustomTextMessage: description: Individual message field matching Stripe's structure type: object required: - message properties: message: description: The actual text message (plain text only, 1-1200 characters) type: string maxLength: 1200 minLength: 1 example: Premium SPF 50 mineral sunscreen example: message: Premium SPF 50 mineral sunscreen Subscription: description: >- 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. type: object required: - cancel_at_period_end - created_at - items - status - subscription_id - test_mode properties: subscription_id: description: Unique identifier for the object. type: string example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: $ref: '#/components/schemas/Timestamptz' description: Time at which the object was created. ISO 8601 format. example: '2026-06-15T14:30:00Z' items: description: The items the customer is subscribed to. type: array items: $ref: '#/components/schemas/V1SubscriptionItem' latest_invoice: description: The ID of the latest invoice generated for this subscription. anyOf: - $ref: '#/components/schemas/Expandable_for_Invoice' - type: 'null' customer: description: The ID of the customer who owns the subscription. anyOf: - $ref: '#/components/schemas/Expandable_for_Customer' - type: 'null' status: $ref: '#/components/schemas/SubscriptionStatus' description: >- Possible values are incomplete, incomplete_expired, trialing, active, past_due, canceled, or unpaid. cancel_at_period_end: description: >- 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. type: boolean example: false current_period_end: description: >- End of the current period that the subscription has been invoiced for. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' current_period_start: description: >- Start of the current period that the subscription has been invoiced for. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' metadata: description: >- A set of key/value pairs that you can attach to a subscription object. type: - object - 'null' example: order_id: '8842' channel: shopify test_mode: description: Whether the subscription is in test mode. type: boolean example: false client_secret: description: >- 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; omitted otherwise. Do not log or store these secrets; expose them only to the customer over TLS. anyOf: - $ref: '#/components/schemas/SubscriptionClientSecret' - type: 'null' proration_behavior: description: The proration behavior for the subscription. anyOf: - $ref: '#/components/schemas/FlexSubscriptionProrationBehavior' - type: 'null' trial_start: description: >- Start of the subscription's trial period, as an RFC 3339 timestamp. `null` if the subscription has no trial. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' trial_end: description: >- End of the subscription's trial period, as an RFC 3339 timestamp. After this time the customer is billed normally. `null` if the subscription has no trial. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' cancel_at: description: >- A future RFC 3339 timestamp at which the subscription will automatically be canceled. `null` unless a future cancellation has been scheduled. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' canceled_at: description: >- The RFC 3339 timestamp at which the subscription was actually canceled. `null` if the subscription has not been canceled. Unlike `cancel_at` (a future scheduled cancellation), this is set once the cancellation has occurred. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' default_payment_method: description: The default payment method for the subscription (expandable). anyOf: - $ref: '#/components/schemas/Expandable_for_PaymentMethod' - type: 'null' example: subscription_id: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' items: - subscription_item_id: fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA quantity: 2500 created_at: '2026-06-15T14:30:00Z' updated_at: '2026-06-15T14:30:00Z' test_mode: false latest_invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: incomplete cancel_at_period_end: false current_period_end: string current_period_start: string metadata: order_id: '8842' channel: shopify test_mode: false client_secret: {} proration_behavior: always_invoice trial_start: string trial_end: string cancel_at: '2026-06-15T14:30:00Z' canceled_at: '2026-06-15T14:30:00Z' default_payment_method: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA Breakdown: description: >- Breakdown of the components that make up the total details. Matches Stripe's structure. See OpenAPI spec: https://github.com/stripe/openapi - schemas: payment_pages_checkout_session_total_details_resource_breakdown type: object properties: discounts: description: The aggregated discounts. type: array items: $ref: '#/components/schemas/DiscountAmount' example: discounts: - discount: {} CardPaymentMethodOptions: description: Card-specific payment options for a Checkout Session. type: object required: - request_three_d_secure properties: request_three_d_secure: $ref: '#/components/schemas/RequestThreeDSecure' description: >- Whether 3D Secure authentication is requested for card payments. One of `automatic` (Default; request only when required), `any` (request whenever supported), or `challenge` (request a customer challenge). example: request_three_d_secure: automatic CollectLetterOfMedicalNecessityAction: description: Data for the collect_letter_of_medical_necessity next action. type: object required: - url properties: url: description: >- The URL where the customer should be redirected to provide the letter. type: string example: https://example.com example: url: https://example.com PaymentFailedAction: description: Data for the payment_failed next action. type: object required: - message - url properties: message: description: A human-readable message describing the payment failure. type: string example: Premium SPF 50 mineral sunscreen url: description: The URL where the customer should be redirected to retry payment. type: string example: https://example.com decline_code: description: The decline code from the payment processor, if available. type: - string - 'null' error_code: description: The error code from the payment processor, if available. type: - string - 'null' example: message: Premium SPF 50 mineral sunscreen url: https://example.com ProvideSecondPaymentMethodAction: description: Data for the provide_second_payment_method next action. type: object required: - eligible_amount - ineligible_amount - message - url properties: message: description: >- A human-readable message explaining that a second payment method is needed. type: string example: Premium SPF 50 mineral sunscreen url: description: >- The URL where the customer should be redirected to provide both payment methods. type: string example: https://example.com eligible_amount: description: The amount in cents for HSA/FSA-eligible items. type: integer format: int32 ineligible_amount: description: The amount in cents for non-eligible items. type: integer format: int32 example: message: Premium SPF 50 mineral sunscreen url: https://example.com eligible_amount: 0 ineligible_amount: 0 ProvideAlternativePaymentMethodAction: description: Data for the provide_alternative_payment_method next action. type: object required: - message - url properties: message: description: >- A human-readable message explaining why an alternative payment method is needed. type: string example: Premium SPF 50 mineral sunscreen url: description: >- The URL where the customer should be redirected to provide a different payment method. type: string example: https://example.com example: message: Premium SPF 50 mineral sunscreen url: https://example.com PartnerMetadata: description: >- The public summary of your account, exposed as the expandable `partner` object embedded on other Flex objects such as checkout sessions, subscriptions, and receipts. type: object required: - name - partner_id - website_url properties: partner_id: description: Unique identifier of the account, prefixed with `facct_`. type: string example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA name: description: Your display name, as shown to customers during checkout. type: string example: Example website_url: description: Your public website URL. type: string description: description: A short description of your business. type: - string - 'null' example: Premium SPF 50 mineral sunscreen example: partner_id: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA name: Example website_url: string description: Premium SPF 50 mineral sunscreen LetterFee: description: Letter-fee details surfaced on the checkout session response. type: object required: - amount - status properties: amount: description: >- Amount charged for the letter, in cents. `0` when waived (disqualified, pre-existing, OTP-verified, existing consultation, etc.). type: integer format: int32 example: 2500 type: description: >- Billing classification. Only present when `amount > 0`. - `"new"` — any new consultation in the checkout (takes precedence when mixed with expired). - `"expired"` — only expired consultation(s) are being re-billed. type: - string - 'null' status: $ref: '#/components/schemas/LetterFeeStatus' description: Collection state of the letter fee. example: amount: 2500 status: pending V1CaptureItem: description: >- A CaptureItem represents the portion of a single line item that was captured as part of a Capture, including the amount taken and the price and payment intent it was settled against. type: object required: - amount_captured - capture_item_id - created_at - test_mode properties: amount_captured: description: >- The amount captured that is associated with this specific capture item type: integer format: int32 example: 2500 capture_item_id: description: The unique identifier for the capture item. type: string example: fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: $ref: '#/components/schemas/Timestamptz' description: The created at timestamp for the capture item example: '2026-06-15T14:30:00Z' price: description: The price id associated with the capture item anyOf: - $ref: '#/components/schemas/Expandable_for_Price' - type: 'null' payment_intent: description: >- ID of the PaymentIntent that this capture item was settled against. `null` if no payment intent is associated with the item. type: - string - 'null' example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: description: Whether the capture item is in test mode type: boolean example: false example: amount_captured: 2500 capture_item_id: fcapi_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' price: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false DisputeStatus: description: The current status of a dispute. oneOf: - type: string enum: - lost - needs_response - under_review - warning_closed - warning_needs_response - warning_under_review - won - description: The dispute was prevented before reaching the card network. type: string enum: - prevented example: lost DisputeReason: description: The reason for the dispute, as reported by the card network. type: string enum: - bank_cannot_process - check_returned - credit_not_processed - customer_initiated - debit_not_authorized - duplicate - fraudulent - general - incorrect_account_details - insufficient_funds - noncompliant - product_not_received - product_unacceptable - subscription_canceled - unrecognized example: bank_cannot_process DisputeEvidenceResponse: description: >- Evidence collected to respond to a dispute, with file references resolved to Flex file IDs. type: object properties: access_activity_log: description: >- A description of the activity on the customer's account or the order, showing that they accessed or used the product or service. type: - string - 'null' customer_name: description: The name of the customer. type: - string - 'null' customer_email_address: description: The email address of the customer. type: - string - 'null' customer_purchase_ip: description: The IP address from which the customer made the purchase. type: - string - 'null' billing_address: description: The billing address provided by the customer. type: - string - 'null' shipping_address: description: The address to which a physical product was shipped. type: - string - 'null' shipping_tracking_number: description: The tracking number for a physical product shipped to the customer. type: - string - 'null' shipping_carrier: description: >- The delivery service that shipped a physical product (e.g., `usps`, `fedex`). type: - string - 'null' shipping_date: description: The date on which a physical product was shipped to the customer. type: - string - 'null' service_date: description: The date on which the service was provided to the customer. type: - string - 'null' product_description: description: >- A description of the product or service purchased and an explanation of why the customer's claim is unwarranted. type: - string - 'null' refund_policy_disclosure: description: Your refund policy as shown to the customer. type: - string - 'null' refund_refusal_explanation: description: An explanation of why the customer is not entitled to a refund. type: - string - 'null' cancellation_policy_disclosure: description: Your cancellation policy as shown to the customer. type: - string - 'null' cancellation_rebuttal: description: >- An explanation of how the customer was shown that the subscription or service was not canceled. type: - string - 'null' duplicate_charge_explanation: description: >- An explanation of the difference between the disputed payment and the charge the customer believes is a duplicate. type: - string - 'null' duplicate_charge_id: description: >- The ID of the charge the customer claims is a duplicate of the disputed charge. type: - string - 'null' uncategorized_text: description: Any additional evidence as free-form text. type: - string - 'null' customer_communication: description: >- File evidence of any communication with the customer, such as emails proving they received the product or service. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' customer_signature: description: >- File evidence of the customer's signature, such as a proof of delivery signed by the customer. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' shipping_documentation: description: >- File documentation showing that a physical product was shipped to the customer (e.g., a shipping label or carrier receipt). anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' receipt: description: >- File evidence of the receipt or message sent to the customer notifying them of the charge. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' duplicate_charge_documentation: description: >- File documentation for the prior charge the customer claims is a duplicate. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' service_documentation: description: >- File documentation showing that a service was provided to the customer. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' uncategorized_file: description: Any additional file evidence that does not fit another category. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' cancellation_policy: description: File evidence of your cancellation policy as shown to the customer. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' refund_policy: description: File evidence of your refund policy as shown to the customer. anyOf: - $ref: '#/components/schemas/EvidenceFileInfo' - type: 'null' example: customer_communication: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer_signature: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA shipping_documentation: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA receipt: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA duplicate_charge_documentation: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA service_documentation: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA uncategorized_file: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA cancellation_policy: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA refund_policy: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA EvidenceDetails: description: Details about the evidence submission deadline and status. type: object required: - has_evidence - past_due - submission_count properties: due_by: description: Deadline for submitting evidence, as an RFC 3339 date-time string. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' has_evidence: description: Whether evidence has been submitted type: boolean example: false past_due: description: Whether the evidence deadline has passed type: boolean example: false submission_count: description: Number of times evidence has been submitted type: integer format: int32 example: 3 example: due_by: '2026-06-15T14:30:00Z' has_evidence: false past_due: false submission_count: 3 DisputeBalanceTransactionInfo: description: >- A summary of a balance transaction associated with a dispute, recording how funds moved on your balance as the dispute progressed (for example the initial debit when the dispute was filed, or the reversal if it was won). type: object required: - amount - balance_transaction_id - fee - net - status properties: balance_transaction_id: description: ID of the balance transaction, prefixed with `fbtxn_`. type: string example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: >- Gross amount of the transaction, in the smallest currency unit (e.g., `2500` = $25.00 USD). Negative when funds are withdrawn from your balance. type: integer format: int32 example: 2500 fee: description: >- Fee applied to the transaction, in the smallest currency unit (e.g., `1500` = $15.00 USD). For a dispute, this is typically the dispute (chargeback) fee. type: integer format: int32 example: 2500 net: description: >- Net amount applied to your balance after fees, in the smallest currency unit (`net = amount - fee`). type: integer format: int32 example: 2500 status: $ref: '#/components/schemas/BalanceTransactionStatus' description: 'Status of the balance transaction: `available` or `pending`.' type: description: >- The type of balance transaction (e.g., `adjustment`). `null` when not classified. type: - string - 'null' reporting_category: description: >- The reporting category used to group the transaction in financial reports. type: - string - 'null' example: example_value category: description: >- The role this transaction plays within the dispute (e.g., the initial debit or a reversal). `null` when not categorized. type: - string - 'null' example: example_value created_at: description: >- Time at which the balance transaction was created, as an RFC 3339 date-time string. `null` when unavailable. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' example: balance_transaction_id: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 fee: 2500 net: 2500 status: available reporting_category: example_value category: example_value created_at: '2026-06-15T14:30:00Z' DisputePaymentMethodDetails: description: Details of the payment method that was disputed. type: object required: - type properties: type: description: The type of payment method that was disputed (e.g., `card`). type: string card: description: >- Card-specific details, present when `type` is `card`. `null` for other payment method types. anyOf: - $ref: '#/components/schemas/DisputePaymentMethodCard' - type: 'null' example: type: string card: brand: visa network_reason_code: example_value TransferData: description: >- 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. type: object required: - destination properties: amount: description: The amount to transfer, in cents. type: - integer - 'null' format: int32 example: 2500 destination: description: The destination account of the transfer. type: string example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA example: amount: 2500 destination: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA PaymentIntentStatus: description: The current lifecycle status of the payment intent. type: string enum: - canceled - processing - requires_action - requires_capture - requires_confirmation - requires_payment_method - succeeded example: canceled Expandable_for_Charge: example: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA anyOf: - type: string example: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Charge' description: An expandable field — either a string ID or an expanded Charge object. Expandable_for_Invoice: example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA anyOf: - type: string example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Invoice' description: An expandable field — either a string ID or an expanded Invoice object. Expandable_for_PaymentMethod: anyOf: - type: string example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/PaymentMethod' example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded PaymentMethod object. PaymentCardType: type: string enum: - primary - secondary x-ms-enum: name: PaymentCardType modelAsString: false values: - value: primary name: Primary description: >- 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. - value: secondary name: Secondary description: >- In a split cart and partial authorization payment, `Secondary` refers to the non-eligible or backup credit card used for ineligible items. description: >- - `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. example: primary LastPaymentError: description: >- Structured error details from the most recent failed payment attempt on a payment intent. type: object required: - type properties: type: description: The type of error (card, invalid_request, api, etc.) type: string code: description: Machine-readable error code (card_declined, expired_card, etc.) type: - string - 'null' decline_code: description: Card-specific decline code (insufficient_funds, lost_card, etc.) type: - string - 'null' message: description: Human-readable error description. type: - string - 'null' payment_method: description: The Flex payment method ID that failed. type: - string - 'null' example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA example: type: string payment_method: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA RefundReason: description: The reason the refund was issued. type: string enum: - duplicate - fraudulent - requested_by_customer - expired_uncaptured_charge example: duplicate RefundStatus: description: The current status of the refund. type: string enum: - pending - requires_action - succeeded - failed - canceled example: pending ReferenceType: description: The kind of reference number associated with the refund. type: string enum: - acquirer_reference_number - system_trace_audit_number - retrieval_reference_number example: acquirer_reference_number ReferenceStatus: description: The status of the refund's acquirer reference. type: string enum: - available - pending - unavailable example: available RefundItem: description: Represents a single refund item (charge that was refunded) type: object required: - amount_refunded properties: amount_refunded: description: The amount refunded from this charge in cents type: integer format: int32 example: 2500 payment_intent: description: The ID of the payment intent that the refund is associated with type: - string - 'null' example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_method_id: description: The ID of the payment method used for this refund type: - string - 'null' example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_id: description: >- Reference number that the customer can use to trace this refund with their bank or card issuer. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: description: Type of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceType' - type: 'null' reference_status: description: Status of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceStatus' - type: 'null' example: amount_refunded: 2500 payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_method_id: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: acquirer_reference_number reference_status: available Expandable_for_BalanceTransaction: anyOf: - type: string example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/BalanceTransaction' example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded BalanceTransaction object. Cart: description: >- One half of a SplitCart: the totals and payment intent for either the HSA/FSA-eligible or the non-eligible items in a split checkout. type: object required: - amount_discount - amount_subtotal - amount_tax - amount_total properties: amount_total: description: >- Total amount for this cart after tax, shipping, and discounts, in the smallest currency unit (e.g., `2500` = $25.00 USD). type: integer format: int32 example: 2500 amount_subtotal: description: >- Sum of the line item amounts before tax, shipping, and discounts, in the smallest currency unit (e.g., `2000` = $20.00 USD). type: integer format: int32 example: 2500 amount_tax: description: >- Total tax applied to this cart, in the smallest currency unit (e.g., `150` = $1.50 USD). type: integer format: int32 example: 2500 amount_discount: description: >- Total discount applied to this cart, in the smallest currency unit (e.g., `500` = $5.00 USD). type: integer format: int32 example: 2500 payment_intent: description: >- The PaymentIntent that collects payment for this cart. `null` until a payment intent has been created for it. Expandable when `split_cart` is expanded with `payment_intent`. anyOf: - $ref: '#/components/schemas/Expandable_for_PaymentIntent' - type: 'null' amount_shipping: description: >- Total shipping charged to this cart, in the smallest currency unit (e.g., `599` = $5.99 USD). `null` when no shipping applies. type: - integer - 'null' format: int32 example: 2500 example: amount_total: 2500 amount_subtotal: 2500 amount_tax: 2500 amount_discount: 2500 payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount_shipping: 2500 V1SubscriptionItem: description: >- A Subscription Item represents a single recurring Price billed as part of a Subscription, together with the quantity of that price the customer is subscribed to. A subscription has one item per recurring price it bills. type: object required: - created_at - price - quantity - subscription_item_id - test_mode properties: subscription_item_id: description: Unique identifier for the subscription item. type: string example: fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA price: $ref: '#/components/schemas/Expandable_for_Price' description: >- The recurring Price this item bills. Returned as a price ID by default, or as the full Price object when expanded. quantity: description: The number of units of the price the customer is subscribed to. type: integer format: int32 example: 2500 created_at: $ref: '#/components/schemas/Timestamptz' description: >- Time at which the subscription item was created, as an RFC 3339 timestamp. example: '2026-06-15T14:30:00Z' updated_at: description: >- Time at which the subscription item was last updated, as an RFC 3339 timestamp. `null` if the item has not been updated since creation. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' test_mode: description: Whether the subscription item exists in test mode. type: boolean example: false example: subscription_item_id: fsubi_01J9XR8M3K7VZ8N2YB4WJ6T0RA price: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA quantity: 2500 created_at: '2026-06-15T14:30:00Z' updated_at: '2026-06-15T14:30:00Z' test_mode: false SubscriptionStatus: description: The current lifecycle status of the subscription. type: string enum: - incomplete - incomplete_expired - trialing - active - past_due - canceled - unpaid - paused example: incomplete SubscriptionClientSecret: description: >- 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. type: object properties: setup_secret: description: >- 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. type: - string - 'null' payment_secret: description: >- 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. type: - string - 'null' example: {} FlexSubscriptionProrationBehavior: description: >- How proration is handled when the subscription changes mid-billing-cycle. type: string enum: - always_invoice - create_prorations - none example: always_invoice DiscountAmount: description: |- A discount applied to the checkout session. Matches Stripe's `line_items_discount_amount` schema. type: object required: - discount properties: discount: $ref: '#/components/schemas/Discount' description: The discount that was applied. example: discount: discount_id: fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA checkout_session: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA subscription: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA source: {} promo_code: fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false end: string start: string RequestThreeDSecure: description: Whether to request 3D Secure authentication on card payments. type: string enum: - automatic - any - challenge example: automatic LetterFeeStatus: type: string enum: - pending - waived - collected - deferred - settled x-ms-enum: name: LetterFeeStatus modelAsString: false values: - value: pending name: Pending description: Fee determined but not yet collected — transient in-flight state. - value: waived name: Waived description: >- No fee applies (disqualified, pre-existing, OTP-verified, etc.). Always paired with `letter_fee_amount = 0` and `billing_type = NULL`. - value: collected name: Collected description: Fee captured as part of the checkout transaction. - value: deferred name: Deferred description: Fee deferred to end-of-month batch settlement. - value: settled name: Settled description: Deferred fee charged via the monthly batch. description: >- Lifecycle state of a [`CheckoutSessionLetterFee`] row. Stored as a lowercase string in the `status` TEXT column (matches the DB default `'pending'` set by migration `20260416001655`). - `pending`: Fee determined but not yet collected — transient in-flight state. - `waived`: No fee applies (disqualified, pre-existing, OTP-verified, etc.). Always paired with `letter_fee_amount = 0` and `billing_type = NULL`. - `collected`: Fee captured as part of the checkout transaction. - `deferred`: Fee deferred to end-of-month batch settlement. - `settled`: Deferred fee charged via the monthly batch. example: pending Expandable_for_Price: anyOf: - type: string example: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Price' example: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded Price object. EvidenceFileInfo: description: A reference to a file attached as dispute evidence. type: object properties: file_id: description: The Flex file ID (e.g., `ffile_xxx`). type: - string - 'null' example: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA filename: description: The original filename from upload. type: - string - 'null' stripe_file_id: description: >- Underlying card-network file ID, present when the file could not be matched to a Flex file ID. type: - string - 'null' example: file_id: ffile_01J9XR8M3K7VZ8N2YB4WJ6T0RA BalanceTransactionStatus: type: string enum: - available - pending x-ms-enum: name: BalanceTransactionStatus modelAsString: false values: - value: available name: Available description: Funds have settled and are available to be paid out. - value: pending name: Pending description: Funds are not yet available. description: |- Availability status of the funds in a balance transaction. - `available`: Funds have settled and are available to be paid out. - `pending`: Funds are not yet available. example: available DisputePaymentMethodCard: description: Card-specific details for a disputed payment made with a card. type: object properties: brand: description: The card brand. `null` when unknown. type: - string - 'null' example: visa network_reason_code: description: >- The reason code the card network assigned to the dispute, as reported by the issuer. type: - string - 'null' example: example_value example: brand: visa network_reason_code: example_value Charge: description: >- A Charge represents a single attempt to move funds for a payment, including its outcome and any 3D Secure, decline, and risk details. A PaymentIntent can have multiple charges over its lifetime (for example after a retry); the most recent is referenced by the PaymentIntent's `latest_charge`. type: object required: - amount - amount_captured - amount_refunded - captured - charge_id - created_at - disputed - paid - payment_intent - refunded - status - test_mode properties: charge_id: description: Unique identifier for the charge. type: string example: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: Amount intended to be collected by this payment. type: integer format: int32 example: 2500 amount_captured: description: >- Amount in cents captured (can be less than the amount attribute on the charge if a partial capture was made). type: integer format: int32 example: 2500 amount_refunded: description: >- Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was made). type: integer format: int32 example: 2500 application_fee_amount: description: The Flex application fee for the charge type: - integer - 'null' format: int32 captured: description: >- If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured. type: boolean example: false created_at: $ref: '#/components/schemas/Timestamptz' description: Time at which the object was created. ISO 8601 format. example: '2026-06-15T14:30:00Z' customer: description: The customer this charge is for if one exists. anyOf: - $ref: '#/components/schemas/Expandable_for_Customer' - type: 'null' invoice: description: The invoice this charge is for if one exists. anyOf: - $ref: '#/components/schemas/Expandable_for_Invoice' - type: 'null' failure_message: description: >- Message to user further explaining reason for charge failure if available. type: - string - 'null' example: Premium SPF 50 mineral sunscreen disputed: description: Whether the charge has been disputed. type: boolean example: false paid: description: >- true if the charge succeeded, or was successfully authorized for later capture. type: boolean example: false refunded: description: >- Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false. type: boolean example: false refunds: description: A list of refunds that have been applied to the charge. type: - array - 'null' items: $ref: '#/components/schemas/Expandable_for_Refund' payment_intent: $ref: '#/components/schemas/Expandable_for_PaymentIntent' description: The payment intent that generated this charge. status: $ref: '#/components/schemas/ChargeStatus' description: The status of the charge. test_mode: description: Whether the charge was created in test mode. type: boolean example: false transfer_group: description: A string that identifies the resulting payment as part of a group type: - string - 'null' example: example_value payment_method_id: description: The ID of the PaymentMethod. type: - string - 'null' example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA three_d_secure: description: 3D Secure authentication outcome details, if 3DS was used. anyOf: - $ref: '#/components/schemas/ThreeDSecureOutcome' - type: 'null' decline_details: description: Decline and risk details for failed or blocked charges. anyOf: - $ref: '#/components/schemas/DeclineDetails' - type: 'null' balance_transaction: description: >- Balance transaction that describes the impact of this charge on your balance. Populated on successful capture, returned as the balance transaction ID. Always serialized; `null` for uncaptured charges. anyOf: - $ref: '#/components/schemas/Expandable_for_BalanceTransaction' - type: 'null' failure_balance_transaction: description: >- Reversal balance transaction created when a captured charge fails or is otherwise reversed and funds are credited back. Always serialized; `null` on the common success path. anyOf: - $ref: '#/components/schemas/Expandable_for_BalanceTransaction' - type: 'null' example: charge_id: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 amount_captured: 2500 amount_refunded: 2500 captured: false created_at: '2026-06-15T14:30:00Z' customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA failure_message: Premium SPF 50 mineral sunscreen disputed: false paid: false refunded: false payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: succeeded test_mode: false transfer_group: example_value payment_method_id: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA three_d_secure: {} decline_details: {} balance_transaction: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA failure_balance_transaction: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA Invoice: description: >- 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. type: object required: - amount_due - amount_paid - collection_method - created_at - invoice_id - status - test_mode - total properties: invoice_id: description: The id of the invoice. type: string example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA total: description: The total amount of the invoice in cents. type: integer format: int32 example: 2500 amount_due: description: The amount due in cents. type: integer format: int32 example: 2500 amount_paid: description: The amount paid in cents. type: integer format: int32 example: 2500 payment_intent: description: >- The payment intent associated with this invoice. The payment intent is created when the invoice is finalized. anyOf: - $ref: '#/components/schemas/Expandable_for_PaymentIntent' - type: 'null' charge: description: The id of the latest charge for this invoice. type: - string - 'null' example: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: description: The id of the customer this invoice is for. anyOf: - $ref: '#/components/schemas/Expandable_for_Customer' - type: 'null' period_end: description: End of the usage period. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' period_start: description: Start of the usage period. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' subscription: description: The subscription that this invoice was prepared for. anyOf: - $ref: '#/components/schemas/Expandable_for_Subscription' - type: 'null' paid_at: description: When the invoice was paid. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' status: $ref: '#/components/schemas/InvoiceStatus' description: The status of the invoice. collection_method: $ref: '#/components/schemas/CollectionMethod' description: >- Either charge_automatically or send_invoice. When charging automatically, Flex will attempt to pay this invoice using the default payment method attached to the customer. When sending an invoice, Flex will email this invoice to the customer with payment instructions. test_mode: description: Whether or not the invoice was created in test mode. type: boolean example: false metadata: description: Metadata associated with the invoice. type: - object - 'null' example: order_id: '8842' channel: shopify created_at: $ref: '#/components/schemas/Timestamptz' description: When the invoice was created. example: '2026-06-15T14:30:00Z' example: invoice_id: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA total: 2500 amount_due: 2500 amount_paid: 2500 payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA charge: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA period_end: string period_start: string subscription: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA paid_at: string status: draft collection_method: charge_automatically test_mode: false metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' PaymentMethod: description: >- 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. type: object required: - billing_details - card - created_at - customer - off_session - payment_method_id - test_mode properties: payment_method_id: description: The ID of the PaymentMethod. type: string example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA billing_details: $ref: '#/components/schemas/BillingDetails' description: >- Billing information associated with the PaymentMethod that may be used or required by particular types of payment methods. customer: $ref: '#/components/schemas/Expandable_for_Customer' description: >- The customer this payment method is attached to. Returned as the customer ID by default; expandable to the full Customer object. metadata: description: >- 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. type: - object - 'null' additionalProperties: type: object example: order_id: '8842' channel: shopify card: $ref: '#/components/schemas/Card' description: User card details. created_at: $ref: '#/components/schemas/Timestamptz' description: Time at which the object was created. ISO 8601 format. example: '2026-06-15T14:30:00Z' test_mode: description: Whether this PaymentMethod is in test mode. type: boolean example: false off_session: description: >- Whether this PaymentMethod is valid for off_session (customer not present) purchase flows. type: boolean example: payment_method_id: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA billing_details: address: {} email: john.doe@example.com name: Example phone: '+14155550142' customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA metadata: order_id: '8842' channel: shopify card: brand: american_express country: US exp_month: 12 exp_year: 2027 fingerprint: abc123 funding: credit last4: '4242' created_at: '2026-06-15T14:30:00Z' test_mode: false off_session: true BalanceTransaction: description: >- A BalanceTransaction represents a single change to your Flex account balance — for example, a charge, refund, dispute, fee, or payout. Each transaction records how much was added or removed, the processing fee, and the resulting net effect on your balance, and links back to the Flex object that caused it. type: object required: - amount - balance_transaction_id - fee - net - status - test_mode properties: balance_transaction_id: description: >- Unique identifier for the balance transaction, prefixed with `fbtxn_`. type: string example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: description: >- Gross amount of the transaction, in the smallest currency unit (e.g., `1000` = $10.00 USD). Positive for funds added to your balance (e.g., charges) and negative for funds removed (e.g., refunds, payouts, dispute debits). type: integer format: int32 example: 2500 available_on: description: >- When the funds become available in your bank account. RFC 3339 timestamp. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' created_at: description: When the transaction was created. RFC 3339 timestamp. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' example: '2026-06-15T14:30:00Z' exchange_rate: description: >- The exchange rate applied if the transaction involved a currency conversion. `null` when no conversion took place. type: - number - 'null' format: double example: 1 fee: description: >- Total processing fee deducted from `amount`, in the smallest currency unit (e.g., `30` = $0.30 USD). `0` when no fee applies. type: integer format: int32 example: 2500 net: description: >- Net amount that affects your balance after `fee` is applied (`net = amount - fee`), in the smallest currency unit (e.g., `970` = $9.70 USD). type: integer format: int32 example: 2500 reporting_category: description: >- High-level accounting category for the transaction. `null` if not yet categorized. type: - string - 'null' example: example_value checkout_session_id: description: >- ID of the Checkout Session that originated this transaction, if it stems from a checkout. type: - string - 'null' example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: description: >- Your own identifier for the originating object, carried over from the checkout session or payment. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: $ref: '#/components/schemas/BalanceTransactionStatus' description: >- Availability status of the funds: `pending` (not yet available) or `available` (settled and withdrawable). source_id: description: >- ID of the Flex object that produced this transaction (e.g., a Charge `fch_`, Refund `fre_`, or Payout `fpo_`). `null` if the source has not been resolved to a Flex object. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: description: The type of transaction. type: - string - 'null' flex_payment_intent_id: description: >- ID of the Payment Intent associated with this transaction, if any. `null` for transactions not tied to a payment (e.g., payouts). type: - string - 'null' example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: description: >- Whether this transaction was created in test mode. `true` for test-mode data, `false` for live data. type: boolean example: false mid: description: >- Merchant identifier (MID) for the account that processed the transaction. type: - string - 'null' example: example_value currency: description: Three-letter ISO currency code, in lowercase (e.g., `usd`). type: - string - 'null' example: usd metadata: description: >- Set of key-value pairs you can attach to the object for storing additional structured information. type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify transaction_fee_amount: description: >- Portion of `fee` attributable to standard transaction processing, in the smallest currency unit. `null` if not broken out. type: - integer - 'null' format: int32 interchange_fee_amount: description: >- Portion of `fee` attributable to card-network interchange, in the smallest currency unit. `null` if not broken out. type: - integer - 'null' format: int32 lmn_fee_amount: description: >- Portion of `fee` attributable to Letter of Medical Necessity (LMN) processing, in the smallest currency unit. `null` if not applicable. type: - integer - 'null' format: int32 dispute_fee_amount: description: >- Portion of `fee` attributable to a dispute, in the smallest currency unit. `null` if not applicable. type: - integer - 'null' format: int32 card_type: description: Card funding type used for the transaction. type: - string - 'null' card_network: description: Card network used for the transaction (e.g., `visa`, `mastercard`). type: - string - 'null' example: balance_transaction_id: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 available_on: string created_at: '2026-06-15T14:30:00Z' exchange_rate: 1 fee: 2500 net: 2500 reporting_category: example_value checkout_session_id: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA client_reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: available source_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA flex_payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false mid: example_value currency: usd metadata: order_id: '8842' channel: shopify Discount: description: >- A Discount object represents the application of a coupon or promotion code to a checkout session, customer, subscription, or invoice. It records which coupon was redeemed, what the discount was applied to, and the time window over which it applies. type: object required: - discount_id - source - start - test_mode properties: discount_id: description: The ID of the discount. type: string example: fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA checkout_session: description: The checkout session that the discount was applied to. type: - string - 'null' example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: description: The customer that the discount was applied to. type: - string - 'null' example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA subscription: description: The subscription that the discount was applied to. type: - string - 'null' example: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice: description: The invoice that the discount was applied to. type: - string - 'null' example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA source: $ref: '#/components/schemas/DiscountSource' description: The source of the discount (coupon or promotion code). promo_code: description: The promo code applied to create the discount. type: - string - 'null' example: fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: description: Whether the discount was applied in test mode type: boolean example: false end: description: >- 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. anyOf: - $ref: '#/components/schemas/Timestamptz' - type: 'null' start: $ref: '#/components/schemas/Timestamptz' description: Date that the coupon was applied. example: discount_id: fdi_01J9XR8M3K7VZ8N2YB4WJ6T0RA checkout_session: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA customer: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA subscription: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA source: coupon: fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: coupon promo_code: fpromo_01J9XR8M3K7VZ8N2YB4WJ6T0RA test_mode: false end: string start: string Price: description: >- 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. type: object required: - active - created_at - price_id - product - test_mode - type - unit_amount properties: price_id: description: The unique identifier for the price. type: string example: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA owner_partner_id: description: >- 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. type: - string - 'null' example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: description: The description of the price. type: - string - 'null' example: Premium SPF 50 mineral sunscreen trial_period_days: description: >- The number of trial period days before the customer is first charged for a recurring price. type: - integer - 'null' format: int32 unit_amount: description: >- The amount to charge per unit, in the smallest currency unit (e.g., `2500` = $25.00 USD). type: integer format: int32 recurring: description: >- The recurring components of a price such as interval and trial period days. anyOf: - $ref: '#/components/schemas/Recurring' - type: 'null' active: description: Whether the price is currently active. type: boolean example: false product: $ref: '#/components/schemas/Expandable_for_Product' description: >- The product this price belongs to. Returned as a product ID by default, or as the full Product object when expanded. created_at: $ref: '#/components/schemas/Timestamptz' description: The date the price was created. example: '2026-06-15T14:30:00Z' type: $ref: '#/components/schemas/PriceType' description: >- The type of the price: a single one-time charge, or a recurring charge billed on a schedule. metadata: description: Metadata information for the price object type: - object - 'null' example: order_id: '8842' channel: shopify hsa_fsa_eligibility: description: The HSA/FSA eligibility for the price. anyOf: - $ref: '#/components/schemas/HSAFSAElegibility' - type: 'null' test_mode: description: Whether the price is in test mode. type: boolean example: false example: price_id: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA owner_partner_id: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: Premium SPF 50 mineral sunscreen unit_amount: 0 recurring: interval: day active: false product: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA created_at: '2026-06-15T14:30:00Z' type: one_time metadata: order_id: '8842' channel: shopify hsa_fsa_eligibility: not_eligible test_mode: false ChargeStatus: description: The outcome of the charge. type: string enum: - succeeded - pending - failed example: succeeded ThreeDSecureOutcome: description: 3D Secure authentication outcome for the charge. type: object properties: authentication_flow: description: 'How the customer was authenticated: `challenge` or `frictionless`.' type: - string - 'null' result: description: Outcome of 3D Secure authentication. type: - string - 'null' result_reason: description: Additional detail about why 3DS succeeded or failed. type: - string - 'null' version: description: The version of 3D Secure used. type: - string - 'null' example: {} DeclineDetails: description: >- Decline and risk details captured at the time of a failed or blocked charge. Absent for successful, non-declined charges. type: object properties: failure_code: description: >- Error code for the charge failure (e.g. `card_declined`, `expired_card`). type: - string - 'null' decline_code: description: >- More specific decline reason (e.g. `insufficient_funds`, `lost_card`). type: - string - 'null' failure_message: description: User-facing failure message. type: - string - 'null' outcome_type: description: The outcome type of the decline. type: - string - 'null' network_status: description: >- Network-level status: `approved_by_network`, `declined_by_network`, etc. type: - string - 'null' seller_message: description: Technical explanation of the outcome for the merchant. type: - string - 'null' reason: description: Fraud/risk reason (e.g. `elevated_risk_level`). type: - string - 'null' risk_level: description: The risk level assessed for the payment. type: - string - 'null' example: {} InvoiceStatus: description: The lifecycle status of the invoice. type: string enum: - draft - open - void - paid - uncollectible example: draft CollectionMethod: description: >- How payment for the invoice is collected: automatically from the customer's saved payment method, or by emailing them an invoice to pay. type: string enum: - charge_automatically - send_invoice example: charge_automatically BillingDetails: description: >- Billing information associated with a PaymentMethod, such as the cardholder's billing address, email, name, and phone number. type: object properties: address: description: The billing address. anyOf: - $ref: '#/components/schemas/BillingAddress' - type: 'null' email: description: The billing email address. type: - string - 'null' example: john.doe@example.com name: description: The billing name. type: - string - 'null' example: Example phone: description: The billing phone number. type: - string - 'null' example: '+14155550142' example: address: city: San Francisco country: US line1: 123 Main St line2: Suite 100 postal_code: '94107' state: CA email: john.doe@example.com name: Example phone: '+14155550142' Card: description: >- A Card object describes the card backing a PaymentMethod, including its brand, funding type, expiration, and the last four digits. type: object required: - brand - country - exp_month - exp_year - fingerprint - funding - last4 properties: brand: $ref: '#/components/schemas/CardBrand' description: The brand of the card. country: description: Two-letter ISO code for the card's country. type: string example: US exp_month: description: The card's expiration month. type: integer format: int32 example: 12 minimum: -128 maximum: 127 exp_year: description: The card's expiration year. type: integer format: int32 example: 2027 fingerprint: description: >- 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. type: string example: abc123 funding: $ref: '#/components/schemas/CardFunding' description: The funding type of the card. last4: description: The last four digits of the card. type: string example: '4242' example: brand: american_express country: US exp_month: 12 exp_year: 2027 fingerprint: abc123 funding: credit last4: '4242' DiscountSource: description: The source of a discount (coupon or promotion code). type: object required: - coupon - type properties: coupon: $ref: '#/components/schemas/Expandable_for_V1Coupon' description: The coupon that was redeemed. type: $ref: '#/components/schemas/DiscountSourceType' description: The type of source. example: coupon: fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: coupon Recurring: description: >- Describes how a recurring price bills over time. Present on prices of type `recurring`; `null` for one-time prices. type: object required: - interval properties: interval: $ref: '#/components/schemas/RecurringInterval' description: The billing cadence for the price. interval_count: description: The number of intervals type: - integer - 'null' format: int64 minimum: 0 maximum: 4294967295 trial_period_days: description: >- 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. type: - integer - 'null' format: int64 minimum: 0 maximum: 4294967295 example: interval: day Expandable_for_Product: anyOf: - type: string example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/Product' example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded Product object. PriceType: description: Whether the price is charged once or on a recurring schedule. type: string enum: - one_time - recurring example: one_time HSAFSAElegibility: description: >- How a product qualifies for HSA/FSA payment, which determines the substantiation required to pay with a benefits card. type: string enum: - not_eligible - auto_substantiation - private_label - letter_of_medical_necessity - prescription - vision - service example: not_eligible BillingAddress: description: A billing address attached to a PaymentMethod's billing details. type: object properties: city: description: City, district, suburb, town, or village. type: - string - 'null' example: San Francisco country: description: Two-letter ISO country code (e.g., `US`). type: - string - 'null' example: US line1: description: Address line 1, such as the street, PO box, or company name. type: - string - 'null' example: 123 Main St line2: description: Address line 2, such as the apartment, suite, unit, or building. type: - string - 'null' example: Suite 100 postal_code: description: ZIP or postal code. type: - string - 'null' example: '94107' state: description: State, county, province, or region. type: - string - 'null' example: CA example: city: San Francisco country: US line1: 123 Main St line2: Suite 100 postal_code: '94107' state: CA CardBrand: description: The card's network (brand). type: string enum: - american_express - diners_club - discover - eftpos_au - JCB - master_card - union_pay - visa - unknown example: american_express CardFunding: description: >- The card's funding type, such as credit, debit, prepaid, or an HSA/FSA benefits card. type: string enum: - credit - debit - hsa_fsa - prepaid - unknown example: credit Expandable_for_V1Coupon: anyOf: - type: string example: fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/V1Coupon' example: fcoup_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: An expandable field — either a string ID or an expanded V1Coupon object. DiscountSourceType: description: The type of discount source. type: string enum: - coupon - promotion_code example: coupon RecurringInterval: description: The frequency at which a recurring price bills. type: string enum: - day - week - month - year example: day Product: description: >- A Product defines what you sell. Flex determines its HSA/FSA eligibility from the name, description, and identifiers you provide. type: object required: - active - created_at - hsa_fsa_eligibility - name - product_id - test_mode properties: product_id: description: The unique identifier for the product. type: string example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA owner_partner_id: description: >- The ID of the account that owns this product. For products shared across an organization this may be a sibling account; otherwise it is your own account ID. type: - string - 'null' example: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA name: description: The name of the product. type: string example: Example description: description: The description of the product. type: - string - 'null' example: Premium SPF 50 mineral sunscreen document_description: description: >- Medical-grade description optimized for use in Letters of Medical Necessity and receipts. deprecated: true type: - string - 'null' receipt_description: description: Shortened description tailored to receipt line items type: - string - 'null' created_at: $ref: '#/components/schemas/Timestamptz' description: The date the product was created. example: '2026-06-15T14:30:00Z' visit_type: description: >- The visit type of the product if a letter of medical necessity is required. anyOf: - $ref: '#/components/schemas/VisitTypeName' - type: 'null' active: description: Determines if the product is active or not. type: boolean example: false upc_code: description: The upc code of the product. type: - string - 'null' gtin: description: The gtin code of the product. type: - string - 'null' reference_gtin: description: >- The GTIN of a private-label reference product, used to establish HSA/FSA eligibility. type: - string - 'null' hsa_fsa_eligibility: $ref: '#/components/schemas/HSAFSAElegibility' description: The elegibility of the product for HSA/FSA. test_mode: description: Whether the product is in test mode or not. type: boolean example: false metadata: description: Metadata associated with the product. type: - object - 'null' additionalProperties: type: string example: order_id: '8842' channel: shopify url: description: The URL of the product. type: - string - 'null' example: https://example.com client_reference_id: description: >- An optional identifier for the product set by the client at creation time. Immutable after creation. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA example: product_id: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA owner_partner_id: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA name: Example description: Premium SPF 50 mineral sunscreen created_at: '2026-06-15T14:30:00Z' visit_type: cbtSleep active: false hsa_fsa_eligibility: not_eligible test_mode: false metadata: order_id: '8842' channel: shopify url: https://example.com client_reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA V1Coupon: description: >- 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: object required: - coupon_id - created_at - duration - name - test_mode - valid properties: coupon_id: description: Unique identifier for the object. type: string example: fcoup_1234567890 amount_off: description: >- Amount that will be taken off the subtotal of any invoices for this customer. type: - integer - 'null' format: int32 example: 2500 applies_to: description: >- An object containing the ID of the product that the coupon can be applied to. anyOf: - $ref: '#/components/schemas/AppliesTo' - type: 'null' duration: $ref: '#/components/schemas/CouponDuration' description: >- One of forever, once, and repeating. Describes how long a customer who applies this coupon will get the discount. duration_in_months: description: >- If duration is repeating, the number of months the coupon applies. Null if coupon duration is forever or once. type: - integer - 'null' format: int32 metadata: description: >- 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. type: - object - 'null' example: order_id: '8842' channel: shopify name: description: Name of the coupon displayed to customers. type: string example: Example percent_off: description: >- Percent that will be taken off the subtotal of any invoices for this customer for the duration of the coupon. type: - number - 'null' format: double max_redemptions: description: >- Maximum number of times this coupon can be redeemed, in total, across all customers, before it is no longer valid. type: - integer - 'null' format: int32 times_redeemed: description: Number of times this coupon has been applied to a customer. type: - integer - 'null' format: int32 valid: description: >- Taking account of the above properties, whether this coupon can still be applied to a customer. type: boolean example: false created_at: $ref: '#/components/schemas/Timestamptz' description: Date when this coupon was created. example: '2026-06-15T14:30:00Z' test_mode: description: Whether the coupon is in test mode type: boolean example: false example: coupon_id: fcoup_1234567890 amount_off: 2500 applies_to: products: [] duration: once metadata: order_id: '8842' channel: shopify name: Example valid: false created_at: '2026-06-15T14:30:00Z' test_mode: false AppliesTo: description: What a coupon's discount is restricted to. anyOf: - type: object required: - products properties: products: description: The product that this coupon applies to. type: array items: type: string example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA - type: object required: - prices properties: prices: description: The price that this coupon applies to. type: array items: type: string example: fprice_01J9XR8M3K7VZ8N2YB4WJ6T0RA - type: object required: - fee_types properties: fee_types: description: The fee types that this coupon applies to. type: array items: $ref: '#/components/schemas/FeeType' - $ref: '#/components/schemas/AppliesToShipping' example: products: - fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA CouponDuration: type: string enum: - once - repeating - forever x-ms-enum: name: CouponDuration modelAsString: false values: - value: once name: Once description: >- Applies to the first charge from a subscription with this coupon applied. - value: repeating name: Repeating description: >- Applies to charges in the first duration_in_months months from a subscription with this coupon applied. - value: forever name: Forever description: >- Applies to all charges from a subscription with this coupon applied. description: >- - `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. example: once AppliesToShipping: description: The coupon applies to shipping. type: string enum: - shipping example: shipping securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: Use a Bearer token to access this API. ````