GET /api/v1/balances/{balance_id}/history

Complete financial ledger for a specific currency balance — top-ups, booking debits, and refunds.

The complete financial ledger for a specific currency balance. Returns every money movement recorded against the balance.

Permission: Read

Call GET /api/v1/balances first to obtain the balance_id for the currency you want to query.

Sandbox: Returns empty data array.

The `source` field

Each entry has a source field:

`source`	What it represents
`"transactions"`	Authoritative balance movements. Recorded every time the balance changes: top-up, booking charge, or refund. Use these for reconciliation totals.
`"flight_balance_operations"`	Per-booking flight audit records. Granular events within a booking lifecycle (initial debit, FX surcharge, adjustment, refund). One booking can produce multiple rows.
`"hotel_balance_operations"`	Per-booking hotel audit records. Same concept as flight operations.

A single action (e.g. confirming a flight) produces both a transactions row and a flight_balance_operations row. Both appear in this response. Sum only transactions rows for financial totals.

Path parameter

Parameter	Description
`{balance_id}`	UUID of the balance row from `GET /api/v1/balances`

Query parameters

Parameter	Type	Description
`from`	string	Inclusive start. ISO-8601 date (`2026-07-01`) or datetime (`2026-07-01T00:00:00Z`)
`to`	string	Inclusive end. Bare dates expand to `23:59:59 UTC`
`type`	string	Filter by type: `CREDIT` \| `DEBIT` \| `REFUND` (applies to `transactions` only)
`page`	integer	1-based page number. Default: `1`
`limit`	integer	Items per page. Range 1–100. Default: `20`

Transaction types

Type	Direction	When it appears
`CREDIT` / `credit`	Funds in	Manual top-ups, deposit returns when a hold is released
`DEBIT` / `debit`	Funds out	Booking confirmations, FX exchange surcharges, manual debit adjustments
`REFUND` / `refund`	Funds in	Full or partial refund after a booking is cancelled or voided

Uppercase values appear in transactions rows; lowercase in *_balance_operations rows.

Request example

curl --get \
    --url https://api.fx-port.com/api/v1/balances/db002f7a-c136-4f32-b19d-38a2542f2af9/history \
    --header 'Authorization: Bearer fxp_live_YOUR_KEY' \
    --data-urlencode 'from=2026-07-01' \
    --data-urlencode 'to=2026-07-31' \
    --data-urlencode 'limit=50'

Response example

{
    "environment": "live",
    "success": true,
    "data": [
        {
            "source": "transactions",
            "id": "3e8b1c02-d7a4-4f5e-9b2a-1c0d8e7f3a91",
            "type": "CREDIT",
            "amount": 2500.00,
            "currency": "DZD",
            "description": "Balance top-up — bank transfer ref TXN-20260711",
            "balanceId": "db002f7a-c136-4f32-b19d-38a2542f2af9",
            "createdAt": "2026-07-11T09:15:00.000000+00:00"
        },
        {
            "source": "flight_balance_operations",
            "id": "658185df-234c-43ba-8175-ba9a5abe6007",
            "type": "debit",
            "amount": 87.50,
            "currency": "DZD",
            "description": "Exchange fee debit for flight booking 4YEK64",
            "bookingRecordId": "136dc334-b581-48c9-8e4c-7ec87cc5f41a",
            "createdAt": "2026-07-09T14:30:00.000000+00:00"
        },
        {
            "source": "transactions",
            "id": "31936df0-299d-429e-b0f5-056a6c0587cc",
            "type": "DEBIT",
            "amount": 5081.44,
            "currency": "DZD",
            "description": "Booking confirmation — flight XE4YCB (ALG → CDG)",
            "balanceId": "db002f7a-c136-4f32-b19d-38a2542f2af9",
            "createdAt": "2026-07-01T15:42:34.272792+00:00"
        },
        {
            "source": "transactions",
            "id": "a4c72d11-08b1-4e3f-b9d8-2e5a1f6c8b02",
            "type": "REFUND",
            "amount": 125.00,
            "currency": "DZD",
            "description": "Partial refund for hotel booking HMPSHEPI1",
            "balanceId": "db002f7a-c136-4f32-b19d-38a2542f2af9",
            "createdAt": "2026-07-01T05:00:09.901817+00:00"
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 50,
        "total": 4,
        "hasMore": false
    },
    "meta": {
        "agencyId": "2e800fb6-0bbf-4fc1-b0bd-0f3be3b5bcc4",
        "balanceId": "db002f7a-c136-4f32-b19d-38a2542f2af9",
        "balanceCurrency": "DZD",
        "environment": "live"
    }
}

Field reference

Field	Present when	Description
`source`	Always	Entry type — see table above
`id`	Always	Entry UUID
`type`	Always	`CREDIT`, `DEBIT`, or `REFUND` (uppercase for transactions; lowercase for operations)
`amount`	Always	Absolute value — always positive. Direction conveyed by `type`.
`currency`	Always	ISO 4217 code — always matches the requested balance currency
`description`	Always	Human-readable label including booking reference and action
`balanceId`	`transactions` only	UUID of the balance this transaction is recorded against
`bookingRecordId`	`*_balance_operations` only	UUID of the internal booking record — use to correlate with a specific booking
`createdAt`	Always	ISO-8601 datetime

Reconciliation tip: A single booking event produces both a transactions row and a flight_balance_operations row. When computing net balance changes, sum only transactions rows. When tracing a specific booking, filter by source = "flight_balance_operations" and bookingRecordId.