Transactions

Update transaction

Amend transaction metadata or custom fields.

The Update Transaction endpoint allows you to modify specific fields of an existing transaction, such as metadata, reference IDs, or custom notes. Core fields like amount, currency, and type cannot be changed once a transaction has been created.

Endpoint

PATCH /v1/transactions/{transaction_id}

Path Parameters

Parameter	Type	Required	Description
transaction_id	string	Yes	Unique ID of the transaction to update.

Headers

Key	Value	Required
Content-Type	application/json	Yes
Authorization	Bearer <access_token>	Yes

Request Body

{
  "reference": "order_98765",
  "metadata": {
    "customer_id": "cus_789",
    "order_id": "ord_456",
    "note": "Priority processing"
  }
}

Field	Type	Required	Description
reference	string	No	Updates the external reference ID.
metadata	object	No	Updates or replaces transaction metadata.

Response

Successful Response (200 OK)

{
  "id": "txn_001",
  "account_id": "acct_001",
  "amount": 5000,
  "currency": "USD",
  "type": "payment",
  "status": "succeeded",
  "reference": "order_98765",
  "metadata": {
    "customer_id": "cus_789",
    "order_id": "ord_456",
    "note": "Priority processing"
  },
  "created_at": "2025-09-18T20:28:00Z",
  "updated_at": "2025-09-18T20:35:00Z"
}

Field	Type	Description
id	string	Transaction ID.
account_id	string	Account linked to the transaction.
amount	int	Amount in minor units (unchangeable).
currency	string	Currency code (unchangeable).
type	string	Transaction type (unchangeable).
status	string	Current status of the transaction.
reference	string	Updated reference value.
metadata	object	Updated metadata.
created_at	string	Timestamp of creation.
updated_at	string	Timestamp of last update.

Error Response (400 / 404 / 409)

{
  "error": "not_found",
  "message": "The transaction could not be found."
}

Error Code	Meaning
invalid_request	Invalid or unsupported update fields.
not_found	Transaction ID does not exist.
conflict	Attempted to update restricted fields (amount, currency, type).

Example Usage

cURL

curl -X PATCH "https://api.example.com/v1/transactions/txn_001" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{
    "reference": "order_98765",
    "metadata": {
      "customer_id": "cus_789",
      "order_id": "ord_456",
      "note": "Priority processing"
    }
  }'

JavaScript (Fetch)

const response = await fetch("https://api.example.com/v1/transactions/txn_001", {
  method: "PATCH",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_access_token"
  },
  body: JSON.stringify({
    reference: "order_98765",
    metadata: {
      customer_id: "cus_789",
      order_id: "ord_456",
      note: "Priority processing"
    }
  })
});

const data = await response.json();
console.log(data.updated_at);

You cannot update the amount, currency, or type of a transaction. For corrections, you should create a refund or a new transaction.

New transaction

Cancel a transaction

Need help? Contact Support

Join our Discord Community

Questions? Contact Sales

On this page

Title