Organizations

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
get/api/v1/organizations/{organizationId}/balances

Request

  • Base URL: https://api-sandbox.koywe.com
  • URL: https://api-sandbox.koywe.com/api/v1/organizations/{organizationId}/balances
  • Auth: HTTP bearer

Path parameters

organizationIdstring required
Example:org3_abc123def456

Organization identifier (UUID format)

Query parameters

merchantIdsstring
Example:mrc_abc123,mrc_def456

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

datestring date-time
Example:2025-10-15T00:00:00.000Z

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

baseCurrency'USD'

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

period'3d' | '7d' | '14d' | '30d' | '90d' | '180d' | '1y' | 'all'

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".

interval'daily' | 'weekly' | 'monthly'

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)
includeMerchantBreakdownboolean
Example:true

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.

excludeTodayboolean
Example:true

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.

OR

Example response

{
  "organizationId": "org3_abc123def456",
  "organizationName": "Acme Corporation",
  "requestedAt": "2025-11-02T18:30:45.123Z",
  "balanceDate": "2025-11-02T18:30:00.000Z",
  "baseCurrency": "USD",
  "merchantCount": 2,
  "summary": {
    "totalsByCurrency": {
      "CLP": "5000000.00",
      "USD": "1250.50",
      "COP": "12500000.00",
      "USDC": "500.25"
    },
    "totalInBaseCurrency": "10399.80",
    "baseCurrency": "USD",
    "totalAccounts": 4,
    "currenciesCount": 4,
    "lastUpdated": "2025-11-02T18:30:00.000Z"
  },
  "exchangeRates": [
    {
      "fromCurrency": "USD",
      "toCurrency": "CLP",
      "rate": "896.86098655",
      "timestamp": "2025-11-02T18:30:45.123Z"
    },
    {
      "fromCurrency": "USD",
      "toCurrency": "COP",
      "rate": "4065.04065041",
      "timestamp": "2025-11-02T18:30:45.123Z"
    },
    {
      "fromCurrency": "USD",
      "toCurrency": "USDC",
      "rate": "1.00020004",
      "timestamp": "2025-11-02T18:30:45.123Z"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.