API Reference

Transactions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Update

PATCH/transactions/{transaction_ref}

Updates a transaction (tags, allocations, or both)

Path ParametersExpand Collapse

transaction_ref: string

Transaction reference. Accepts either an encoded Fragment ID (txn_xxx) or an external ID.

Body ParametersJSONExpand Collapse

current_transaction_version: number

Current transaction version for optimistic concurrency control.

allocations: optional object { create, update }

create: optional array of object { amount, invoice_id, type, user }

Allocations to add to the transaction

amount: string

Amount to allocate in smallest currency unit as stringified bigint.

invoice_id: string

The invoice to allocate against.

type: "invoice_payin" or "invoice_payout"

The type of allocation.

Accepts one of the following:

"invoice_payin"

"invoice_payout"

user: object { id } or object { external_id }

Identifies a user by Fragment-generated id or external_id (request body).

Accepts one of the following:

ID = object { id }

id: string

FRAGMENT generated ID of the user

ExternalID = object { external_id }

external_id: string

External ID of the user

update: optional array of object { id, amount }

Existing allocations to update

id: string

The ID of the allocation to update.

amount: string

New amount in smallest currency unit as stringified bigint.

tags: optional object { create, delete, set, update }

create: optional array of object { key, value }

Tags to add. Prefer set unless you specifically want create-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

delete: optional array of object { key }

Tags to remove by key

key: string

Tag key to delete

set: optional array of object { key, value }

Tags to create or overwrite without requiring the caller to distinguish between create and update.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

update: optional array of object { key, value }

Tags to update. The key identifies the existing tag; the value is the new value. Prefer set unless you specifically want update-only validation.

key: string

Tag key. Must be a valid safe string (no special characters like #, /, :). Max 50 characters.

value: string

Tag value. Must be a valid safe string (no special characters like #, /, :). Max 200 characters.

ReturnsExpand Collapse

data: Transaction { id, account, allocations, 9 more }

Transaction object.

id: string

User-facing encoded transaction ID.

account: object { id, external_id }

External account reference on transaction responses.

id: string

User-facing encoded account ID.

external_id: string

External account reference ID.

allocations: array of object { amount, invoice_id, type, user }

amount: string

Allocated amount in smallest currency unit as stringified bigint.

invoice_id: string

The invoice this allocation is applied against.

type: "invoice_payin" or "invoice_payout"

The type of allocation.

Accepts one of the following:

"invoice_payin"

"invoice_payout"

user: object { id, external_id }

User reference in API responses: Fragment user id and external_id.

id: string

FRAGMENT generated ID of the user

external_id: string

External ID of the user

amount: string

Amount in smallest currency unit as stringified bigint (can be positive or negative).

created: string

Creation timestamp.

formatdate-time

currency: "ADA" or "BTC" or "DAI" or 176 more

Currency code (ISO 4217 or crypto)

Accepts one of the following:

"ADA"

"BTC"

"DAI"

"ETH"

"SOL"

"USDC"

"USDT"

"USDG"

"EURC"

"CADC"

"CADT"

"XLM"

"UNI"

"BCH"

"LTC"

"AAVE"

"LINK"

"MATIC"

"PTS"

"AED"

"AFN"

"ALL"

"AMD"

"ANG"

"AOA"

"ARS"

"AUD"

"AWG"

"AZN"

"BAM"

"BBD"

"BDT"

"BGN"

"BHD"

"BIF"

"BMD"

"BND"

"BOB"

"BRL"

"BSD"

"BTN"

"BWP"

"BYR"

"BZD"

"CAD"

"CDF"

"CHF"

"CLP"

"CNY"

"COP"

"CRC"

"CUC"

"CUP"

"CVE"

"CZK"

"DJF"

"DKK"

"DOP"

"DZD"

"EGP"

"ERN"

"ETB"

"EUR"

"FJD"

"FKP"

"GBP"

"GEL"

"GGP"

"GHS"

"GIP"

"GMD"

"GNF"

"GTQ"

"GYD"

"HKD"

"HNL"

"HRK"

"HTG"

"HUF"

"IDR"

"ILS"

"IMP"

"INR"

"IQD"

"IRR"

"ISK"

"JMD"

"JOD"

"JPY"

"KES"

"KGS"

"KHR"

"KMF"

"KPW"

"KRW"

"KWD"

"KYD"

"KZT"

"LAK"

"LBP"

"LKR"

"LRD"

"LSL"

"LYD"

"MAD"

"MDL"

"MGA"

"MKD"

"MMK"

"MNT"

"MOP"

"MUR"

"MVR"

"MWK"

"MXN"

"MYR"

"MZN"

"NAD"

"NGN"

"NIO"

"NOK"

"NPR"

"NZD"

"OMR"

"PAB"

"PEN"

"PGK"

"PHP"

"PKR"

"PLN"

"PYG"

"QAR"

"RON"

"RSD"

"RUB"

"RWF"

"SAR"

"SBD"

"SCR"

"SDG"

"SEK"

"SGD"

"SHP"

"SLL"

"SOS"

"SPL"

"SRD"

"SVC"

"SYP"

"STN"

"SZL"

"THB"

"TJS"

"TMT"

"TND"

"TOP"

"TRY"

"TTD"

"TVD"

"TWD"

"TZS"

"UAH"

"UGX"

"USD"

"UYU"

"UZS"

"VEF"

"VND"

"VUV"

"WST"

"XAF"

"XCD"

"XOF"

"XPF"

"YER"

"ZAR"

"ZMW"

"LOGICAL"

"CUSTOM"

external_id: string

External idempotency key provided by the user.

posted: string

Posted timestamp in ISO 8601 format.

formatdate-time

tags: array of object { key, value }

Metadata tags associated with this transaction.

key: string

Tag key

value: string

Tag value

unallocated_amount: string

Read-only amount not yet allocated.

version: number

Current version of the transaction, used for optimistic concurrency control.

modified: optional string

Last modified timestamp.

formatdate-time

Update

HTTP

HTTP

TypeScript

Python

curl https://api.us-west-2.fragment.dev/transactions/$TRANSACTION_REF \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -d '{
          "current_transaction_version": 0,
          "tags": {
            "set": [
              {
                "key": "region",
                "value": "eu-west-1"
              }
            ]
          }
        }'

200 example

{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "allocations": [
      {
        "amount": "1000",
        "invoice_id": "inv_abc123",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "external_id": "bank_txn_123",
    "posted": "2026-02-12T00:00:00.000Z",
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "version": 1,
    "modified": "2026-02-12T01:00:00.000Z"
  }
}

Returns Examples

200 example

{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "allocations": [
      {
        "amount": "1000",
        "invoice_id": "inv_abc123",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "external_id": "bank_txn_123",
    "posted": "2026-02-12T00:00:00.000Z",
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "version": 1,
    "modified": "2026-02-12T01:00:00.000Z"
  }
}