Payments API ReferenceOrganizations

Get organization balance aggregation with multi-currency conversion

Retrieves aggregated virtual account balances across all merchants in an organization with optional currency conversion. **Features:** - Aggregates all virtual accounts across merchants the user has access to - Converts balances to a user-selectable base currency (default: USD) - Supports merchant filtering via merchantIds parameter - Two modes: current/point-in-time balance OR historical time-series data - Includes organization-wide summaries and optional per-merchant breakdowns in snapshots **Permission Model:** Only returns data for merchants where the user has MERCHANT_BANK_ACCOUNTS_SETTINGS_VIEW_VIRTUAL_ACCOUNT permission. If the user has no access to any merchants in the organization, a 403 Forbidden error (OB00002) is returned. **Note:** This endpoint specifically queries virtual accounts only (isVirtual=true), therefore it requires the view_virtual_account permission rather than view_external_bank_account. **Current Balance Mode:** Provide neither `date` nor `period` for latest balances, or provide `date` for a specific point in time. Returns organization-wide summary. **Historical Mode:** Provide `period` parameter (e.g., "30d") to receive time-series data. The `interval` is auto-selected based on period unless explicitly provided. Use `includeMerchantBreakdown=true` to get per-merchant details in each snapshot. **Example Requests:** - Current balance (all merchants): `GET /organizations/:orgId/balances?baseCurrency=USD` - Current balance (filtered merchants): `GET /organizations/:orgId/balances?merchantIds=mrc_123,mrc_456&baseCurrency=USD` - Point-in-time balance: `GET /organizations/:orgId/balances?date=2025-10-15T00:00:00.000Z` - Historical (7 days, auto interval): `GET /organizations/:orgId/balances?period=7d&baseCurrency=USD` - Historical (30 days, weekly, with breakdown): `GET /organizations/:orgId/balances?period=30d&interval=weekly&includeMerchantBreakdown=true&baseCurrency=USD` - Historical (filtered merchants): `GET /organizations/:orgId/balances?merchantIds=mrc_123&period=14d&interval=daily`

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path Parameters

organizationIdstringRequired

Organization identifier (UUID format)

Headers

x-admin-api-keystringRequired

Query Parameters

merchantIdsstringOptional

Optional comma-separated list of merchant IDs to filter results. Only merchants the user has access to will be included.

datedatetimeOptional

Optional ISO 8601 date for point-in-time balance snapshot. Mutually exclusive with period parameter.

baseCurrency"USD"Optional

Base currency for conversion (ISO 4217 code). Currently only USD is supported. Defaults to USD if not provided.

periodenumOptional
Time period for historical data. Mutually exclusive with date parameter. Values: 3d, 7d, 14d, 30d, 90d, 180d, 1y, all. **Interval Auto-Selection** (if interval not provided): 3d/7d/14d→daily, 30d/90d→weekly, 180d/1y/all→monthly. **Restrictions**: Daily interval only allowed for periods ≤14d. Weekly only for periods ≤180d. Monthly required for periods >180d or "all".
intervalenumOptional
Data point frequency for historical mode. Auto-selected based on period if not provided. Values: daily, weekly, monthly. **Performance Restrictions**: - daily: Only allowed with periods 3d, 7d, or 14d (max 14 data points) - weekly: Allowed with periods 3d, 7d, 14d, 30d, 90d, or 180d (max ~26 data points) - monthly: Allowed with any period, required for 180d, 1y, or all (max ~24 data points)
Allowed values:
includeMerchantBreakdownbooleanOptionalDefaults to false

Include per-merchant breakdown in historical snapshots. Default: false. When true, each snapshot includes detailed merchant balances with currency conversions. Set to false for better performance with large datasets.

excludeTodaybooleanOptionalDefaults to false

Exclude today’s snapshot from historical data for better cache performance. When true, only historical data (ending at yesterday) is returned, and currentSummary is omitted. Use this pattern: fetch current balance separately for real-time updates, while historical chart data uses aggressive caching. Default: false

Response

Balance aggregation retrieved successfully. Response type depends on whether period parameter is provided.
object

Returned when neither date nor period is provided (current balance), or when date parameter is specified (point-in-time balance)

OR
object

Returned when period parameter is provided (e.g., ?period=30d). Includes time-series snapshots with optional per-merchant breakdown controlled by includeMerchantBreakdown parameter.

Errors