> ## 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 Refunds > Returns a list of your refunds, most recent first. ## OpenAPI ````yaml /openapi.json get /v1/refunds 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/refunds: get: tags: - Refunds summary: List Refunds description: Returns a list of your refunds, most recent first. operationId: v1.refunds.list parameters: - in: query name: status description: Filter by refund status. schema: description: Filter by refund status. anyOf: - $ref: '#/components/schemas/RefundStatus' - type: 'null' style: form - in: query name: payment_intent description: Filter by payment intent ID. schema: description: Filter by payment intent ID. examples: - fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: checkout_session description: Filter by checkout session ID. schema: description: Filter by checkout session ID. examples: - fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fcs_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: starting_after description: >- A cursor for use in pagination. `starting_after` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, ending with `fre_xyz`, your subsequent call can include `starting_after=fre_xyz` to fetch the next page. schema: description: >- A cursor for use in pagination. `starting_after` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, ending with `fre_xyz`, your subsequent call can include `starting_after=fre_xyz` to fetch the next page. examples: - fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA - in: query name: ending_before description: >- A cursor for use in pagination. `ending_before` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, starting with `fre_abc`, your subsequent call can include `ending_before=fre_abc` to fetch the previous page. schema: description: >- A cursor for use in pagination. `ending_before` is a refund ID that defines your place in the list. For instance, if you make a list request and receive 20 refunds, starting with `fre_abc`, your subsequent call can include `ending_before=fre_abc` to fetch the previous page. examples: - fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA type: - string - 'null' style: form example: fre_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/MultipleRefundsBody_for_Refund' example: refunds: - refund_id: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 created_at: '2026-06-15T14:30:00Z' status: pending test_mode: false metadata: order_id: '8842' channel: shopify reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA items: [] subscription_id: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice_id: fin_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: - refunds:read components: schemas: RefundStatus: description: The current status of the refund. type: string enum: - pending - requires_action - succeeded - failed - canceled example: pending MultipleRefundsBody_for_Refund: description: An envelope wrapping a list of refund objects. type: object required: - refunds properties: refunds: description: The list of refund objects. type: array items: $ref: '#/components/schemas/Refund' example: refunds: - refund_id: fre_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_intent_id: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA amount: 2500 created_at: '2026-06-15T14:30:00Z' status: pending test_mode: false metadata: order_id: '8842' channel: shopify reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA items: [] subscription_id: fsub_01J9XR8M3K7VZ8N2YB4WJ6T0RA invoice_id: fin_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 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 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 RefundReason: description: The reason the refund was issued. type: string enum: - duplicate - fraudulent - requested_by_customer - expired_uncaptured_charge example: duplicate ReferenceType: description: The kind of reference number associated with the refund. type: string enum: - acquirer_reference_number - system_trace_audit_number - retrieval_reference_number example: acquirer_reference_number ReferenceStatus: description: The status of the refund's acquirer reference. type: string enum: - available - pending - unavailable example: available RefundItem: description: Represents a single refund item (charge that was refunded) type: object required: - amount_refunded properties: amount_refunded: description: The amount refunded from this charge in cents type: integer format: int32 example: 2500 payment_intent: description: The ID of the payment intent that the refund is associated with type: - string - 'null' example: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_method_id: description: The ID of the payment method used for this refund type: - string - 'null' example: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_id: description: >- Reference number that the customer can use to trace this refund with their bank or card issuer. type: - string - 'null' example: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: description: Type of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceType' - type: 'null' reference_status: description: Status of the reference number used for the refund anyOf: - $ref: '#/components/schemas/ReferenceStatus' - type: 'null' example: amount_refunded: 2500 payment_intent: fpi_01J9XR8M3K7VZ8N2YB4WJ6T0RA payment_method_id: fpm_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_id: obj_01J9XR8M3K7VZ8N2YB4WJ6T0RA reference_type: acquirer_reference_number reference_status: available Expandable_for_BalanceTransaction: anyOf: - type: string example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA - $ref: '#/components/schemas/BalanceTransaction' example: fbtxn_01J9XR8M3K7VZ8N2YB4WJ6T0RA description: >- An expandable field — either a string ID or an expanded BalanceTransaction object. 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 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 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: Use a Bearer token to access this API. ````