> ## 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 Invoices > List invoices ## OpenAPI ````yaml /openapi.json get /v1/invoices 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/invoices: get: tags: - Invoices summary: List Invoices description: List invoices operationId: v1.invoices.list parameters: - 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: customer description: Filter invoices by customer ID schema: description: Filter invoices by customer ID examples: - fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fcus_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: starting_after description: >- A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, ending with `fin_xyz`, your subsequent call can include `starting_after=fin_xyz` to fetch the next page. schema: description: >- A cursor for use in pagination. `starting_after` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, ending with `fin_xyz`, your subsequent call can include `starting_after=fin_xyz` to fetch the next page. examples: - fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: ending_before description: >- A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, starting with `fin_abc`, your subsequent call can include `ending_before=fin_abc` to fetch the previous page. schema: description: >- A cursor for use in pagination. `ending_before` is an invoice ID that defines your place in the list. For instance, if you make a list request and receive 20 invoices, starting with `fin_abc`, your subsequent call can include `ending_before=fin_abc` to fetch the previous page. examples: - fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA - 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 20. schema: description: >- A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. examples: - 10 type: - integer - 'null' format: int32 maximum: 100 minimum: 1 style: form example: 10 responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MultipleInvoicesBody_for_Invoice' example: invoices: - invoice_id: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA total: 2500 amount_due: 2500 amount_paid: 2500 charge: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: draft collection_method: charge_automatically test_mode: false metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' '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 components: schemas: MultipleInvoicesBody_for_Invoice: description: An envelope wrapping a list of invoice objects. type: object required: - invoices properties: invoices: description: The list of invoices. type: array items: $ref: '#/components/schemas/Invoice' example: invoices: - invoice_id: fin_01J9XR8M3K7VZ8N2YB4WJ6T0RA total: 2500 amount_due: 2500 amount_paid: 2500 charge: fch_01J9XR8M3K7VZ8N2YB4WJ6T0RA status: draft collection_method: charge_automatically test_mode: false metadata: order_id: '8842' channel: shopify created_at: '2026-06-15T14:30:00Z' 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 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' 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_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_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. Timestamptz: description: >- A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). type: string example: string 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. 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 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 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 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 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. 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_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 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 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 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 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 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. 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. 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: {} 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. 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' 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 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 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 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 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 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 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 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 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: Use a Bearer token to access this API. ````