---
title: "Update Refund"
method: PATCH
path: "/v1/refunds/{refund_id}"
tags: ["Refunds"]
---

# Update Refund

`PATCH /v1/refunds/{refund_id}`

Updates the `reason` and/or `metadata` of an existing refund. Only these two fields can be changed; the refund amount, status, and associated payment cannot be modified after creation. Supplied metadata keys are merged into any existing metadata.

## Path parameters

- `refund_id` string, required

## Request body

- RefundBodyForUpdateRefundRequest — An envelope wrapping a single refund object.
  - `refund` UpdateRefundRequest, required — Parameters for updating a refund. Only `reason` and `metadata` can be changed; all fields are optional and omitted fields are left unchanged.
    - `reason` 'duplicate' | 'fraudulent' | 'requested_by_customer' | 'expired_uncaptured_charge' — The reason the refund was issued.
    - `metadata` object, nullable — Set of key-value pairs to attach to the refund. Supplied keys are merged into any existing metadata rather than replacing it.

## Response `200`

An envelope wrapping a single refund object.

- RefundBodyForRefund — An envelope wrapping a single refund object.
  - `refund` Refund, required — 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.
    - `refund_id` string, required — The ID of the refund
    - `payment_intent_id` string, nullable — The ID of the payment intent that the refund is associated with
    - `amount` integer, required — The amount of the refund in cents
    - `created_at` string, required — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
    - `reason` 'duplicate' | 'fraudulent' | 'requested_by_customer' | 'expired_uncaptured_charge' — The reason the refund was issued.
    - `status` 'pending' | 'requires_action' | 'succeeded' | 'failed' | 'canceled', required — The current status of the refund.
    - `test_mode` boolean, required — Whether the refund was created in test mode
    - `metadata` object, nullable — Metadata attached to the refund
    - `reference_id` string, nullable — Reference number that the customer can use to trace this refund with their bank or card issuer.
    - `reference_type` 'acquirer_reference_number' | 'system_trace_audit_number' | 'retrieval_reference_number' — The kind of reference number associated with the refund.
    - `reference_status` 'available' | 'pending' | 'unavailable' — The status of the refund's acquirer reference.
    - `items` RefundItem[] — List of refund items (charges that were refunded)
      - `amount_refunded` integer, required — The amount refunded from this charge in cents
      - `payment_intent` string, nullable — The ID of the payment intent that the refund is associated with
      - `payment_method_id` string, nullable — The ID of the payment method used for this refund
      - `reference_id` string, nullable — Reference number that the customer can use to trace this refund with their bank or card issuer.
      - `reference_type` 'acquirer_reference_number' | 'system_trace_audit_number' | 'retrieval_reference_number' — The kind of reference number associated with the refund.
      - `reference_status` 'available' | 'pending' | 'unavailable' — The status of the refund's acquirer reference.
    - `subscription_id` string, nullable — The subscription this refund is associated with (for subscription cancellation refunds)
    - `invoice_id` string, nullable — The invoice this refund is associated with (for subscription billing period refunds)
    - `balance_transaction` union — An expandable field — either a string ID or an expanded BalanceTransaction object.
      - string
      - BalanceTransaction — 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.
        - `balance_transaction_id` string, required — Unique identifier for the balance transaction, prefixed with `fbtxn_`.
        - `amount` integer, required — 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).
        - `available_on` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
        - `created_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
        - `exchange_rate` number, double, nullable — The exchange rate applied if the transaction involved a currency conversion. `null` when no conversion took place.
        - `fee` integer, required — Total processing fee deducted from `amount`, in the smallest currency unit (e.g., `30` = $0.30 USD). `0` when no fee applies.
        - `net` integer, required — Net amount that affects your balance after `fee` is applied (`net = amount - fee`), in the smallest currency unit (e.g., `970` = $9.70 USD).
        - `reporting_category` string, nullable — High-level accounting category for the transaction. `null` if not yet categorized.
        - `checkout_session_id` string, nullable — ID of the Checkout Session that originated this transaction, if it stems from a checkout.
        - `client_reference_id` string, nullable — Your own identifier for the originating object, carried over from the checkout session or payment.
        - `status` 'available' | 'pending', required — 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.
        - `source_id` string, nullable — 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, nullable — The type of transaction.
        - `flex_payment_intent_id` string, nullable — ID of the Payment Intent associated with this transaction, if any. `null` for transactions not tied to a payment (e.g., payouts).
        - `test_mode` boolean, required — Whether this transaction was created in test mode. `true` for test-mode data, `false` for live data.
        - `mid` string, nullable — Merchant identifier (MID) for the account that processed the transaction.
        - `currency` string, nullable — Three-letter ISO currency code, in lowercase (e.g., `usd`).
        - `metadata` object, nullable — Set of key-value pairs you can attach to the object for storing additional structured information.
        - `transaction_fee_amount` integer, nullable — Portion of `fee` attributable to standard transaction processing, in the smallest currency unit. `null` if not broken out.
        - `interchange_fee_amount` integer, nullable — Portion of `fee` attributable to card-network interchange, in the smallest currency unit. `null` if not broken out.
        - `lmn_fee_amount` integer, nullable — Portion of `fee` attributable to Letter of Medical Necessity (LMN) processing, in the smallest currency unit. `null` if not applicable.
        - `dispute_fee_amount` integer, nullable — Portion of `fee` attributable to a dispute, in the smallest currency unit. `null` if not applicable.
        - `card_type` string, nullable — Card funding type used for the transaction.
        - `card_network` string, nullable — Card network used for the transaction (e.g., `visa`, `mastercard`).
    - `failure_balance_transaction` union — An expandable field — either a string ID or an expanded BalanceTransaction object.
      - string
      - BalanceTransaction — 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.
        - `balance_transaction_id` string, required — Unique identifier for the balance transaction, prefixed with `fbtxn_`.
        - `amount` integer, required — 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).
        - `available_on` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
        - `created_at` string — A timestamp encoded as an RFC 3339 / ISO 8601 string (e.g. `2026-06-15T14:30:00Z`).
        - `exchange_rate` number, double, nullable — The exchange rate applied if the transaction involved a currency conversion. `null` when no conversion took place.
        - `fee` integer, required — Total processing fee deducted from `amount`, in the smallest currency unit (e.g., `30` = $0.30 USD). `0` when no fee applies.
        - `net` integer, required — Net amount that affects your balance after `fee` is applied (`net = amount - fee`), in the smallest currency unit (e.g., `970` = $9.70 USD).
        - `reporting_category` string, nullable — High-level accounting category for the transaction. `null` if not yet categorized.
        - `checkout_session_id` string, nullable — ID of the Checkout Session that originated this transaction, if it stems from a checkout.
        - `client_reference_id` string, nullable — Your own identifier for the originating object, carried over from the checkout session or payment.
        - `status` 'available' | 'pending', required — 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.
        - `source_id` string, nullable — 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, nullable — The type of transaction.
        - `flex_payment_intent_id` string, nullable — ID of the Payment Intent associated with this transaction, if any. `null` for transactions not tied to a payment (e.g., payouts).
        - `test_mode` boolean, required — Whether this transaction was created in test mode. `true` for test-mode data, `false` for live data.
        - `mid` string, nullable — Merchant identifier (MID) for the account that processed the transaction.
        - `currency` string, nullable — Three-letter ISO currency code, in lowercase (e.g., `usd`).
        - `metadata` object, nullable — Set of key-value pairs you can attach to the object for storing additional structured information.
        - `transaction_fee_amount` integer, nullable — Portion of `fee` attributable to standard transaction processing, in the smallest currency unit. `null` if not broken out.
        - `interchange_fee_amount` integer, nullable — Portion of `fee` attributable to card-network interchange, in the smallest currency unit. `null` if not broken out.
        - `lmn_fee_amount` integer, nullable — Portion of `fee` attributable to Letter of Medical Necessity (LMN) processing, in the smallest currency unit. `null` if not applicable.
        - `dispute_fee_amount` integer, nullable — Portion of `fee` attributable to a dispute, in the smallest currency unit. `null` if not applicable.
        - `card_type` string, nullable — Card funding type used for the transaction.
        - `card_network` string, nullable — Card network used for the transaction (e.g., `visa`, `mastercard`).

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error
- `429` — Too Many Requests

---

[API](https://skmtc.dev/withflex/apis/flex-api.md) · [All operations](https://skmtc.dev/withflex/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withflex/flex-api/revisions/b1560fc2f199/schema)