FRAGMENT

Billing Reference

F Transactions#

a. Create

#

Syncs a transaction, optionally with allocations

POST /transactions
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.create(
  {
      account: {
        external_id: 'acct_external_123',
        id: 'ext_account_YWJjMTIz'
      },
      allocations: [],
      amount: '-1000',
      currency: 'USD',
      external_id: 'bank_txn_123',
      posted: '2026-02-12T00:00:00.000Z'
    }
);
Parameters
external_id
string, required
External transaction ID used for idempotent sync.
account
object, required
Account reference. Provide id, external_id, or both.
posted
datetime, required
Posted timestamp in ISO 8601 format.
currency
ADA | BTC | DAI | ..., required
Currency code (ISO 4217 or crypto)
amount
Int64, required
Amount in smallest currency unit as stringified bigint (can be positive or negative).
allocations
object[], required
Allocation entries for this transaction. Empty indicates unreconciled funds.
tags
object[]
Optional metadata tags for this transaction
Response
{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "modified": "2026-02-12T01:00:00.000Z",
    "version": 1
  }
}

b. Create Allocations

#

Updates allocations on an existing transaction

POST /transactions/{transaction_ref}/allocations
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.createAllocations(
  'txn_abc123',
  {
      allocation_updates: [
        {
          amount: '1000',
          invoice_id: 'inv_abc123',
          op: 'add',
          type: 'invoice_payin',
          user: { id: 'user_abc123' }
        }
      ],
      version: 1
    }
);
Parameters
transaction_ref
string, required
Transaction reference. Accepts either an encoded Fragment ID (txn_xxx) or an external ID.
version
integer, required
Current transaction version for optimistic concurrency control
allocation_updates
object[], required
Allocation operations to apply
Response
{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "modified": "2026-02-12T01:00:00.000Z",
    "version": 1
  }
}

c. List

#

Lists all transactions for the workspace

GET /transactions
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.list(
  {
      account: 'ext_account_YWJjMTIz',
      reconciliation_status: 'reconciled'
    }
);
Parameters
reconciliation_status
reconciled | unreconciled
Filter by reconciliation state. reconciled = unallocated_amount === 0; unreconciled = unallocated_amount !== 0. Omit for all transactions.
account
string
Filter by account. Encoded account ID (ext_account_xxx) or external_id. If the account does not exist, returns an empty list.
Response
{
  "data": [
    {
      "id": "txn_dHhuX2ZyYWdfMDAx",
      "external_id": "bank_txn_123",
      "account": {
        "id": "ext_account_YWJjMTIz",
        "external_id": "acct_external_123"
      },
      "posted": "2026-02-12T00:00:00.000Z",
      "currency": "USD",
      "amount": "-1000",
      "allocations": [
        {
          "invoice_id": "inv_abc123",
          "amount": "1000",
          "type": "invoice_payin",
          "user": {}
        }
      ],
      "tags": [
        {
          "key": "region",
          "value": "us-east"
        }
      ],
      "unallocated_amount": "-1000",
      "created": "2026-02-12T00:00:00.000Z",
      "modified": "2026-02-12T01:00:00.000Z",
      "version": 1
    }
  ]
}

d. List History

#

Gets the version history of a transaction

GET /transactions/{transaction_ref}/history
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.listHistory('txn_abc123');
Parameters
transaction_ref
string, required
Transaction reference. Accepts either an encoded Fragment ID (txn_xxx) or an external ID.
Response
{
  "data": [
    {
      "id": "txn_dHhuX2ZyYWdfMDAx",
      "external_id": "bank_txn_123",
      "account": {
        "id": "ext_account_YWJjMTIz",
        "external_id": "acct_external_123"
      },
      "posted": "2026-02-12T00:00:00.000Z",
      "currency": "USD",
      "amount": "-1000",
      "allocations": [
        {
          "invoice_id": "inv_abc123",
          "amount": "1000",
          "type": "invoice_payin",
          "user": {}
        }
      ],
      "tags": [
        {
          "key": "region",
          "value": "us-east"
        }
      ],
      "unallocated_amount": "-1000",
      "created": "2026-02-12T00:00:00.000Z",
      "modified": "2026-02-12T01:00:00.000Z",
      "version": 1
    }
  ]
}

e. Retrieve

#

Gets a transaction by ID or external ID

GET /transactions/{transaction_ref}
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.retrieve('txn_abc123');
Parameters
transaction_ref
string, required
Transaction reference. Accepts either an encoded Fragment ID (txn_xxx) or an external ID.
Response
{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "modified": "2026-02-12T01:00:00.000Z",
    "version": 1
  }
}

f. Update

#

Updates a transaction (tags, allocations, or both)

PATCH /transactions/{transaction_ref}
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.update(
  'txn_abc123',
  {
      current_transaction_version: 1,
      tags: { update: [{ key: 'region', value: 'eu-west-1' }] }
    }
);
Parameters
transaction_ref
string, required
Transaction reference. Accepts either an encoded Fragment ID (txn_xxx) or an external ID.
current_transaction_version
integer, required
Current transaction version for optimistic concurrency control.
tags
object
allocations
object
Response
{
  "data": {
    "id": "txn_dHhuX2ZyYWdfMDAx",
    "external_id": "bank_txn_123",
    "account": {
      "id": "ext_account_YWJjMTIz",
      "external_id": "acct_external_123"
    },
    "posted": "2026-02-12T00:00:00.000Z",
    "currency": "USD",
    "amount": "-1000",
    "allocations": [
      {
        "invoice_id": "inv_abc123",
        "amount": "1000",
        "type": "invoice_payin",
        "user": {
          "id": "user_abc123",
          "external_id": "user-ext-001"
        }
      }
    ],
    "tags": [
      {
        "key": "region",
        "value": "us-east"
      }
    ],
    "unallocated_amount": "-1000",
    "created": "2026-02-12T00:00:00.000Z",
    "modified": "2026-02-12T01:00:00.000Z",
    "version": 1
  }
}

g. Search

#

Searches transactions by filter criteria

POST /transactions/search
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.search(
  {
      filter: {
        account: {
          any: [
            {
              external_id: 'acct_external_123',
              id: 'ext_account_YWJjMTIz'
            }
          ]
        }
      }
    }
);
Parameters
filter
object, required
Filter criteria for searching transactions.
Response
{
  "data": [
    {
      "id": "txn_dHhuX2ZyYWdfMDAx",
      "external_id": "bank_txn_123",
      "account": {
        "id": "ext_account_YWJjMTIz",
        "external_id": "acct_external_123"
      },
      "posted": "2026-02-12T00:00:00.000Z",
      "currency": "USD",
      "amount": "-1000",
      "allocations": [
        {
          "invoice_id": "inv_abc123",
          "amount": "1000",
          "type": "invoice_payin",
          "user": {}
        }
      ],
      "tags": [
        {
          "key": "region",
          "value": "us-east"
        }
      ],
      "unallocated_amount": "-1000",
      "created": "2026-02-12T00:00:00.000Z",
      "modified": "2026-02-12T01:00:00.000Z",
      "version": 1
    }
  ]
}

h. Search Allocations

#

Searches transaction allocations by filter criteria

POST /transactions/allocations/search
import Fragment from '@fragment-dev/ts-node';

const client = new Fragment({
  clientId: process.env['FRAGMENT_CLIENT_ID'],
  clientSecret: process.env['FRAGMENT_CLIENT_SECRET'],
});

const response = await client.transactions.searchAllocations({ filter: { invoice_id: { any: ['inv_abc123'] } } });
Parameters
filter
object, required
Filter criteria for searching transaction allocations.
Response
{
  "data": [
    {
      "invoice_id": "inv_abc123",
      "amount": "1000",
      "type": "invoice_payin",
      "user": {
        "id": "user_abc123",
        "external_id": "user-ext-001"
      },
      "id": "alloc_abc123",
      "posted": "2026-02-12T00:00:00.000Z",
      "transaction": {
        "id": "txn_dHhuX2ZyYWdfMDAx",
        "external_id": "bank_txn_123"
      }
    }
  ]
}
©
 FRAGMENT  
2026
○ Light
○ Dark
● System