> ## 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 Promo Codes > Returns a list of your promotion codes. Optionally filter by `active`. ## OpenAPI ````yaml /openapi.json get /v1/promo_codes 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/promo_codes: get: tags: - Promo Codes summary: List Promo Codes description: Returns a list of your promotion codes. Optionally filter by `active`. operationId: v1.promo_codes.list parameters: - in: query name: active description: Specifies whether the promo code is currently active. schema: description: Specifies whether the promo code is currently active. examples: - false type: - boolean - 'null' style: form example: false responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/MultiplePromoCodesBody_for_PromoCode' example: promo_codes: - promo_code_id: fpromo_01HACM7FZ1084XB1GB6053VM0E code: SUMMER2016 coupon: coupon_id: fcoup_1234567890 amount_off: 100 applies_to: null duration: once duration_in_months: null metadata: key: value name: Coupon percent_off: 10 max_redemptions: 100 times_redeemed: 0 valid: true created_at: '2024-05-17T14:59:21Z' test_mode: true max_redemptions: 100 times_redeemed: 0 created_at: '2024-05-17T14:59:21Z' customer: fcus_01HACM7FZ1084XB1GB6053VM0D active: true metadata: key: value test_mode: false '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: - promo_codes:read components: schemas: MultiplePromoCodesBody_for_PromoCode: description: An envelope wrapping a list of promotion code objects. type: object required: - promo_codes properties: promo_codes: description: The list of promotion codes. type: array items: $ref: '#/components/schemas/PromoCode' example: promo_codes: - promo_code_id: fpromo_01HACM7FZ1084XB1GB6053VM0E code: SUMMER2016 coupon: coupon_id: fcoup_1234567890 amount_off: 100 applies_to: null duration: once duration_in_months: null metadata: key: value name: Coupon percent_off: 10 max_redemptions: 100 times_redeemed: 0 valid: true created_at: '2024-05-17T14:59:21Z' test_mode: true max_redemptions: 100 times_redeemed: 0 created_at: '2024-05-17T14:59:21Z' customer: fcus_01HACM7FZ1084XB1GB6053VM0D active: true metadata: key: value test_mode: false 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 PromoCode: description: >- A promo code represents a code for a coupon that can be redeemed by a customer. type: object required: - active - code - coupon - created_at - promo_code_id - test_mode - times_redeemed properties: promo_code_id: description: The ID of the promo code. type: string example: fpromo_01HACM7FZ1084XB1GB6053VM0E code: description: >- The customer-facing code. Regardless of case, this code must be unique across all active type: string example: SUMMER2016 coupon: $ref: '#/components/schemas/V1Coupon' description: The coupon that the promo code represents. example: coupon_id: fcoup_1234567890 amount_off: 100 applies_to: null duration: once duration_in_months: null metadata: key: value name: Coupon percent_off: 10 max_redemptions: 100 times_redeemed: 0 valid: true created_at: '2024-05-17T14:59:21Z' test_mode: true max_redemptions: description: The number of times the promo code can be redeemed. type: - integer - 'null' format: int32 example: 100 times_redeemed: description: The number of times the promo code has been redeemed. type: integer format: int32 example: 0 created_at: $ref: '#/components/schemas/Timestamptz' description: The date and time the promo code was created. example: '2024-05-17T14:59:21Z' customer: description: >- The customer that can be associated with the promo code. If null, the promo code can be redeemed by any customer. type: - string - 'null' example: fcus_01HACM7FZ1084XB1GB6053VM0D active: description: Whether the promo code is currently active. type: boolean example: true metadata: description: Metadata associated with the promo code. type: - object - 'null' example: key: value test_mode: description: Whether the promo code is in test mode. type: boolean example: false example: promo_code_id: fpromo_01HACM7FZ1084XB1GB6053VM0E code: SUMMER2016 coupon: coupon_id: fcoup_1234567890 amount_off: 100 applies_to: null duration: once duration_in_months: null metadata: key: value name: Coupon percent_off: 10 max_redemptions: 100 times_redeemed: 0 valid: true created_at: '2024-05-17T14:59:21Z' test_mode: true max_redemptions: 100 times_redeemed: 0 created_at: '2024-05-17T14:59:21Z' customer: fcus_01HACM7FZ1084XB1GB6053VM0D active: true metadata: key: value test_mode: false 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 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 Timestamptz: description: >- A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`). type: string example: string 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 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 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. ````