Checkout.com API logo

Balances

View the balances for sub-accounts in an entity.

Retrieve entity balances

Use this endpoint to retrieve balances for each sub-account in an entity.
Note: The sub-account is referred to as currency account in the API.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
id
required
string

The ID of the entity.

Example: ent_w4jelhppmfiufdnatam37wrfc4
query Parameters
query
string

The query to apply to limit the currency accounts.

Example: query=currency:EUR
withCurrencyAccountId
boolean
Default: false

Specifies if the response should include the sub-account ID that corresponds to each set of balances.

balancesAt
string <date-time>

A UTC datetime to retrieve historical balances at a specific point in time, in the format yyyy-MM-ddTHH:mm:ssZ (e.g. 2026-05-06T13:59:59.9999999+00:00). Must be in the past. If omitted, the response returns live balances.

Example: balancesAt=2026-05-06T13:59:59.9999999+00:00
Responses
200

Balances retrieved successfully.

400

Invalid query parameter — for example, an unsupported query filter value, a non-boolean withCurrencyAccountId, or a malformed balancesAt value.

401

Unauthorized

404

Entity not found

422

Invalid data was sent

get/balances/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Balances;
using Checkout.Common;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Balances)
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();


BalancesQuery query = new BalancesQuery {Query = "currency:" + Currency.GBP};

try
{
    BalancesResponse balances = await api.BalancesClient()
        .RetrieveEntityBalances("entitiy_id", query);
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples
application/json
{
  • "data": [
    ]
}
➔ Next to Payment Context