# Update a transfer reversal

> Update a reversal's `description` or `metadata`. The amount cannot be changed. Send only the fields you want to change.

Source: https://help.boltapp.com/api-reference/transfers/transfer-reversals/updatetransferreversal

`PATCH /v3/transfers/{id}/reversals/{reversal_id}`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "title": "Transfers API",
    "version": "v3",
    "description": "Move funds between your marketplace account and a seller's, independently of any order or\npayment.\n\nUse Transfers to pay sellers on your own schedule: after fulfilment, after a returns window, or\non a weekly payout run. Each transfer draws on your Bolt balance and reaches the seller on\ntheir next payout.\n\nSellers are identified by the seller ID you registered with Bolt when you onboarded them, the\nsame value you pass as `X-Bolt-Connect-Seller-Id` and in `seller_splits`.\n\nTransfers must be enabled for a seller before you can use them. See the Transfers tag\ndescription for the full prerequisites.\n"
  },
  "servers": [
    {
      "url": "https://api.boltapp.com",
      "description": "The Production URL (Live Data)."
    },
    {
      "url": "https://api-sandbox.boltapp.com",
      "description": "The Sandbox URL (Test Data)."
    }
  ],
  "security": [
    {
      "X-API-Key": [],
      "X-Publishable-Key": []
    }
  ],
  "paths": {
    "/v3/transfers/{id}/reversals/{reversal_id}": {
      "patch": {
        "operationId": "updateTransferReversal",
        "summary": "Update a transfer reversal",
        "description": "Update a reversal's `description` or `metadata`. The amount cannot be changed. Send only\nthe fields you want to change.\n",
        "tags": [
          "Transfer Reversals"
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/TransferId"
          },
          {
            "$ref": "#/components/parameters/ReversalId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TransferReversalUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The reversal was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransferReversal"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/TransferError"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "TransferId": {
        "in": "path",
        "name": "id",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "The ID of the transfer to operate on.",
        "examples": {
          "default": {
            "value": "trf_9f8e7d6c5b"
          }
        }
      },
      "ReversalId": {
        "in": "path",
        "name": "reversal_id",
        "required": true,
        "schema": {
          "type": "string"
        },
        "description": "The ID of the reversal to operate on.",
        "examples": {
          "default": {
            "value": "trr_4a3b2c1d0e"
          }
        }
      },
      "IdempotencyKey": {
        "in": "header",
        "name": "Idempotency-Key",
        "required": false,
        "schema": {
          "type": "string"
        },
        "description": "Bolt's standard replay protection for `POST` and `PATCH` requests. Use a UUID, up to 255\ncharacters. A key can only be replayed on an identical request, and a replayed response\ncarries `Idempotent-Replayed: true`. Concurrent requests sharing a key return `409`. Keys\nexpire after 24 hours.\n\nOn Create transfer this is secondary to `reference`, whose protection does not expire.\n",
        "examples": {
          "default": {
            "value": "8f14e45f-ea8f-4b3c-9b1a-0d1c2e3f4a5b"
          }
        }
      }
    },
    "schemas": {
      "TransferReversalUpdateRequest": {
        "type": "object",
        "description": "Only `description` and `metadata` can be changed.",
        "properties": {
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "examples": [
              "Partial return, 1 of 3 items"
            ]
          },
          "metadata": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Metadata"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Metadata": {
        "type": "object",
        "description": "Your own key-value pairs, for storing your references against the object. Up to 20 keys,\nwith keys up to 40 characters and values up to 500 characters. An object with no metadata\nreturns `{}` rather than null.\n",
        "additionalProperties": {
          "type": "string"
        },
        "examples": [
          {
            "invoice": "INV-2026-0114"
          }
        ]
      },
      "TransferReversal": {
        "type": "object",
        "description": "A movement of funds back the way the transfer sent them, in whole or in part. It is\nincluded in a payout and sent to the bank like any transfer, so it carries its own status\nand is not instantaneous. A reversal is never `cancelled`.\n",
        "required": [
          "id",
          "created_at",
          "transfer_id",
          "status",
          "amount",
          "metadata"
        ],
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "description": "The reversal's ID. Treat it as an opaque string.",
            "examples": [
              "trr_4a3b2c1d0e"
            ]
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true,
            "description": "When the reversal was created.",
            "examples": [
              "2026-10-20T11:02:44Z"
            ]
          },
          "transfer_id": {
            "type": "string",
            "readOnly": true,
            "description": "The transfer being reversed.",
            "examples": [
              "trf_9f8e7d6c5b"
            ]
          },
          "status": {
            "type": "string",
            "description": "How far the reversal has progressed, using the same meanings as a transfer's status. A\nreversal is never `cancelled`.\n",
            "enum": [
              "pending",
              "in_transit",
              "paid",
              "failed"
            ],
            "examples": [
              "pending"
            ]
          },
          "amount": {
            "allOf": [
              {
                "$ref": "#/components/schemas/Amount"
              }
            ],
            "description": "The amount reversed. Always greater than zero, and never more than the transfer's\nunreversed remainder.\n"
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 255,
            "description": "The reference you supplied when creating the reversal, if you supplied one.",
            "examples": [
              "reversal-return-8831"
            ]
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 500,
            "description": "Your own note on the reversal. Can be changed later.",
            "examples": [
              "Partial return, 1 of 3 items"
            ]
          },
          "payout_reference": {
            "type": [
              "string",
              "null"
            ],
            "readOnly": true,
            "description": "The Bolt payout that carried this reversal, for reconciling against your statement.",
            "examples": [
              "po_20261021_0044"
            ]
          },
          "metadata": {
            "$ref": "#/components/schemas/Metadata"
          }
        }
      },
      "Amount": {
        "type": "object",
        "description": "A monetary amount: a base unit amount and a supported currency.",
        "required": [
          "currency",
          "units"
        ],
        "properties": {
          "currency": {
            "type": "string",
            "description": "The currency of the transfer. Both sides must settle in it: there is no currency\nconversion.\n",
            "enum": [
              "AUD",
              "CAD",
              "EUR",
              "GBP",
              "USD"
            ],
            "examples": [
              "USD"
            ]
          },
          "units": {
            "type": "integer",
            "format": "int64",
            "description": "The amount in the currency's base units, for example cents for USD and EUR.",
            "examples": [
              4000
            ]
          }
        }
      },
      "FieldError": {
        "type": "object",
        "description": "A validation failure on a specific request field.\n\nFields you can expect: `seller_id` when the seller is unknown to your marketplace, cannot\nbe paid out, or does not settle in the currency, `direction` when it is missing or not one\nof the two values, `amount` when it is not greater than zero or is above the per-transfer\nlimit, `amount.currency` when the currency is not supported or not one both sides settle\nin, `reference` when it is missing or too long, and `transfer_permissions` when transfers\nare not enabled for that seller in that direction.\n",
        "required": [
          ".tag",
          "message",
          "field"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "invalid_input_parameter"
            ],
            "examples": [
              "invalid_input_parameter"
            ]
          },
          "message": {
            "type": "string",
            "examples": [
              "payouts are not enabled for seller seller_4471"
            ]
          },
          "field": {
            "type": "string",
            "description": "The field that failed validation, in its hierarchical form.",
            "examples": [
              "transfer_permissions"
            ]
          }
        }
      },
      "TransferStateError": {
        "type": "object",
        "description": "The request is valid but the transfer is in the wrong state for it. Retrying an identical\nrequest will fail the same way: resolve the state first.\n",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "transfer_not_cancelable",
              "transfer_not_reversible",
              "transfer_already_reversed",
              "reversal_amount_exceeds_remaining"
            ],
            "examples": [
              "transfer_not_reversible"
            ]
          },
          "message": {
            "type": "string",
            "examples": [
              "Transfer trf_9f8e7d6c5b is pending and cannot be reversed. Cancel it instead."
            ]
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "description": "The type of error returned. Branch on this value rather than on the message.",
            "enum": [
              "unauthorized",
              "forbidden",
              "not_found",
              "idempotency_conflict",
              "rate_limited",
              "unprocessable_request"
            ],
            "examples": [
              "not_found"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human readable description of the error, which may include details of the request\nthat was made. It is written for developers, is not localized, and should not be shown\nto shoppers.\n",
            "examples": [
              "We were unable to process your request."
            ]
          }
        }
      }
    },
    "responses": {
      "TransferError": {
        "description": "The transfer operation cannot complete.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/FieldError"
                },
                {
                  "$ref": "#/components/schemas/TransferStateError"
                },
                {
                  "$ref": "#/components/schemas/Error"
                }
              ]
            },
            "examples": {
              "unknownSeller": {
                "summary": "The seller ID is not one of your registered sellers",
                "value": {
                  ".tag": "invalid_input_parameter",
                  "field": "seller_id",
                  "message": "no seller was found with ID seller_4471"
                }
              },
              "transfersNotEnabled": {
                "summary": "Transfers are not enabled for this seller in this direction",
                "value": {
                  ".tag": "invalid_input_parameter",
                  "field": "transfer_permissions",
                  "message": "payouts are not enabled for seller seller_4471"
                }
              },
              "overLimit": {
                "summary": "The amount is above the per-transfer limit set for this seller",
                "value": {
                  ".tag": "invalid_input_parameter",
                  "field": "amount",
                  "message": "amount exceeds the per-transfer limit set for this seller"
                }
              },
              "currencyNotSettled": {
                "summary": "One side does not settle in this currency",
                "value": {
                  ".tag": "invalid_input_parameter",
                  "field": "amount.currency",
                  "message": "seller seller_4471 does not settle in USD"
                }
              },
              "notReversible": {
                "summary": "A reversal was attempted on a transfer that has not been paid",
                "value": {
                  ".tag": "transfer_not_reversible",
                  "message": "Transfer trf_9f8e7d6c5b is pending and cannot be reversed. Cancel it instead."
                }
              }
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The API key or publishable key is missing, invalid, or used against the wrong environment.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "default": {
                "value": {
                  ".tag": "unauthorized",
                  "message": "The request could not be authenticated."
                }
              }
            }
          }
        }
      },
      "NotFound": {
        "description": "No such transfer or reversal, or it belongs to another marketplace.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "examples": {
              "default": {
                "value": {
                  ".tag": "not_found",
                  "message": "No transfer was found with ID trf_9f8e7d6c5b."
                }
              }
            }
          }
        }
      }
    },
    "securitySchemes": {
      "X-API-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key",
        "description": "Your Bolt API key, from Developer > API in the Bolt Merchant Dashboard. Server-side only.\nSandbox keys work only against `api-sandbox.boltapp.com`. Using a sandbox key against\nproduction, or the reverse, returns `401`.\n"
      },
      "X-Publishable-Key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Publishable-Key",
        "description": "The publicly shareable identifier for your merchant division. Your authenticated account is\nalways one side of a transfer, and seller IDs are resolved against it.\n"
      }
    }
  }
}
```