> ## 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 Products

> Returns a list of your products, sorted by creation date with the most recently created products appearing first. By default only active products are returned; pass `active=false` to list archived ones. You can also filter by `client_reference_id` or by metadata using `metadata[key]=value` query parameters.



## OpenAPI

````yaml /openapi.json get /v1/products
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/products:
    get:
      tags:
        - Products
      summary: List Products
      description: >-
        Returns a list of your products, sorted by creation date with the most
        recently created products appearing first. By default only active
        products are returned; pass `active=false` to list archived ones. You
        can also filter by `client_reference_id` or by metadata using
        `metadata[key]=value` query parameters.
      operationId: v1.products.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: int32
            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: int32
            minimum: 0
          style: form
          example: 3
        - in: query
          name: starting_after
          description: >-
            A cursor for use in pagination. `starting_after` is a product ID
            that defines your place in the list.
          schema:
            description: >-
              A cursor for use in pagination. `starting_after` is a product ID
              that defines your place in the list.
            examples:
              - fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
            type:
              - string
              - 'null'
          style: form
          example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
        - in: query
          name: ending_before
          description: >-
            A cursor for use in pagination. `ending_before` is a product ID that
            defines your place in the list.
          schema:
            description: >-
              A cursor for use in pagination. `ending_before` is a product ID
              that defines your place in the list.
            examples:
              - fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
            type:
              - string
              - 'null'
          style: form
          example: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
        - in: query
          name: active
          description: Only return products where `active` matches this value.
          schema:
            description: Only return products where `active` matches this value.
            examples:
              - false
            type:
              - boolean
              - 'null'
          style: form
          example: false
        - in: query
          name: client_reference_id
          description: Filter products by their client-provided product identifier.
          schema:
            description: Filter products by their client-provided product identifier.
            examples:
              - example_value
            type:
              - string
              - 'null'
          style: form
          example: example_value
        - in: query
          name: metadata
          description: >-
            Filter by metadata key-value pairs using bracket syntax. For
            example: `metadata[lookup_key]=premium-plan`. Multiple keys use AND
            logic.
          schema:
            type: object
            example:
              lookup_key: premium-plan
          style: deepObject
          example:
            lookup_key: premium-plan
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MultipleProductsBody_for_Product'
              example:
                products:
                  - product_id: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
                    owner_partner_id: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA
                    name: Example
                    description: Premium SPF 50 mineral sunscreen
                    created_at: '2026-06-15T14:30:00Z'
                    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
        '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:
            - products:read
components:
  schemas:
    MultipleProductsBody_for_Product:
      description: An envelope wrapping a list of product objects.
      type: object
      required:
        - products
      properties:
        products:
          description: The list of products.
          type: array
          items:
            $ref: '#/components/schemas/Product'
      example:
        products:
          - product_id: fprod_01J9XR8M3K7VZ8N2YB4WJ6T0RA
            owner_partner_id: facct_01J9XR8M3K7VZ8N2YB4WJ6T0RA
            name: Example
            description: Premium SPF 50 mineral sunscreen
            created_at: '2026-06-15T14:30:00Z'
            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
    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
    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
    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
    Timestamptz:
      description: >-
        A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g.
        `2026-06-15T14:30:00Z`).
      type: string
      example: string
    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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use a Bearer token to access this API.

````