Balances Endpoints - Criteo Docs

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

Getting StartedLearn more about balances here.

Backward compatibility for balance endpoints:

The poNumber field on balance responses is removed in 2026-01 and replaced by two separate fields: retailerPoNumber and criteoPoNumber. This is a breaking change for consumers of GET /balances on prior versions who rely on poNumber.
All other new fields (retailerId, privateMarketBillingType) are additive. Retailer budgets are hidden by default on prior API versions.

You can learn more about retailer budgets on this page.

Endpoints

Method	Endpoint	Description
GET	`/accounts/{accountId}/balances`	Retrieve all balances associated with a specific account.
GET	`/accounts/{accountId}/balances/{balanceId}`	Retrieve a specific balance
POST	`/accounts/{accountId}/balances`	Create a new balance for a specified account.
PATCH	`/accounts/{accountId}/balances/{balanceId}`	Modify balance’s metadata (name, start/end date - for deposited funds, see below)
POST	`/accounts/{accountId}/balances/{balanceId}/add-funds`	Add/remove funds deposited in a specific balance.
GET	`/balances/{balanceId}/campaigns`	Retrieve all campaigns linked to a specific balance.
POST	`/balances/{balanceId}/campaigns/append`	Add campaigns to a specific balance.
POST	`/balances/{balanceId}/campaigns/delete`	Remove campaigns from a specific balance.
GET	`/balances/{balanceId}/history`	Retrieve all changes made historically to a balance

Balance Parameters

Attribute	Data Type	Description
`id`	`string`	Balance ID Accepted values: string of int64 Writeable? N / Nullable? N
`name`*	`string`	Balance name Accepted values: up to 255-char strings Writeable? Y / Nullable? N
`deposited`	`decimal`	Amount of funds deposited; uncapped if`null` Accepted values:`deposited`≥ 0.0 Writeable? Y / Nullable? Y
`spent`	`decimal`	Amount of funds already spent Accepted values: 0 ≤`spent`≤`deposited` Writeable? N / Nullable? N
`remaining`	`decimal`	Amount of funds remaining Accepted values: 0 ≤`remaining`≤`deposited` (or`null`, if`deposited`not set) Writeable? N / Nullable? Y
`startDate`*	`timestamp`	Balance start date; if time zone is not set, will consider Account‘s time zone as default Accepted values:`yyyy-mm-dd` (in ISO-8601) Writeable? Y / Nullable? N
`endDate`	`timestamp`	Balance end date; if time zone is not set, will consider Account‘s time zone as default Accepted values:`yyyy-mm-dd` (in ISO-8601) Default: if`null` or absent, balance will be available indefinitely Writeable? Y / Nullable? Y
`status`	`enum`	Balance current status Accepted values:`active`, `scheduled`, `ended`, `unknown` Writeable? N / Nullable? N
`createdAt`	`timestamp`	Timestamp of balance creation, in UTC Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in ISO-8601) Writeable? N / Nullable? N
`updatedAt`	`timestamp`	Timestamp of last balance update, in UTC Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in ISO-8601) Writeable? N / Nullable? N
`memo`	`string`	An optional memo note that can be set in the balance Accepted values: up to 250-char strings Writeable? Y / Nullable? Y
`balanceType`	`enum`	The balance type is computed based on the deposited amount: Accepted values:`capped`, `uncapped`, `unknown` Writeable? N / Nullable? N - `capped`: if the deposited amount is provided. - `uncapped`: when there is no amount defined (set to`null`)
`spendType`*	`enum`	The type of balance that will be used based on the campaign type Accepted values:`Onsite`, `Offsite`, `OffsiteAwareness` Writeable? N / Nullable? N
`privateMarketBillingType`	`enum`	Billing type of the balance Accepted values:`notApplicable`, `billByRetailer`, `billByCriteo` ⚠️ Note: - balances created through the API will, automatically, be denoted as`billByRetailer` - only balances denoted as`billByRetailer`can be modified through the API - `billByCriteo`are balances created in our Commerce Max platform and can only be edited in our UI - `notApplicable`is an initial or default value if the`privateMarketBillingType`is not set yet. If it is observed it would be treated as the default value`billByRetailer`. Writeable? N / Nullable? N
`retailerId`	`string`	Retailer this balance is scoped to. Present only on retailer budgets. Nullable? Y (null for balances without retailer budgets)
`retailerPoNumber`	`string?`	Retailer purchase order number. Replaces the removed`poNumber`field. Nullable? Y
`criteoPoNumber`	`string?`	Criteo purchase order number. Replaces the removed`poNumber`field. Nullable? Y
`poNumber`	`string`	Purchase order number. Removed since 2026.01 and replaced by`retailerPoNumber`and`criteoPoNumber` Accepted values: up to 32-char strings Writeable? Y / Nullable? Y

*Required for Balance creation

Balance History Parameters

Attribute	Data Type	Description
`dateOfModification`	`timestamp`	Timestamp of balance update Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in ISO-8601) Writeable? N / Nullable? N
`modifiedByUser`	`string`	Username who modified the insertion order Accepted values: strings in format “j.doe” Writeable? N / Nullable? N
`changeType`	`enum`	Definition of the type of change in a balance Accepted values: `BalanceCreated`, `BalanceCapped`, `BalanceUncapped`, `EndDate`, `StartDate`, `RetailerPoNumber`, `ValueAdd` - `BalanceCreated`: new balance is created - `BalanceUncapped`: capped balance is changed to uncapped - `BalanceCapped`: uncapped balance is changed to capped - `StartDate`: start date is modified - `EndDate`: end date is modified
`changeDetails`	`object`	Structure with the change details (from Balance History endpoint) Parameters: - `previousValue`: previous value of a property of the balance - `currentValue`: current value of a property of the balance - `changeValue`: change value of a property of the balance

Get all Balances for an Account

This endpoint lists all balances in an account. Results are paginated using pageIndex and pageSize query parameters; if omitted, defaults to 0 and 25, respectively. See API Response.

On API version 2026-07 and later, retailer budgets are included and retailerId, retailerPoNumber, and criteoPoNumber are returned. The old poNumber field is removed.

Learn more on retailer budgets here.Legacy version behavior (2026-01 and earlier): Only standard Criteo budget balances are returned. retailerId, retailerPoNumber, and criteoPoNumber are not present in the response. The legacy poNumber field is present.

Sample Request

cURL

curl -X GET "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=0&pageSize=25" \
    -H "Authorization: Bearer <MY_ACCESS_TOKEN>"

Sample Response - Versions prior to 2026.07

{
    "metadata": {
        "totalItemsAcrossAllPages": 94,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 4,
        "nextPage": "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=1&pageSize=25"
    },
    "data": [
        {
            "id": "14094543095747588032",
            "type": "BalanceResponseV2",
            "attributes": {
                "name": "Balance 123",
                "poNumber": "13993827",
                "memo": "uncapped balance, free to spend!",
                "deposited": null,
                "spent": 42931.28,
                "remaining": null,
                "startDate": "2020-04-06",
                "endDate": null,
                "status": "active",
                "createdAt": "2020-04-06T00:02:41+00:00",
                "updatedAt": "2020-04-06T00:02:41+00:00",
                "balanceType": "uncapped",
                "spendType": "Onsite",
                "privateMarketBillingType": "notApplicable"
            }
        },
        // ...
        {
            "id": "4237496305219757554",
            "type": "BalanceResponseV2",
            "attributes": {
                "name": "Balance 789",
                "poNumber": "",
                "memo": "10k for the special 2s-day promotion",
                "deposited": 10000.00,
                "spent": 923.40,
                "remaining": 9076.60,
                "startDate": "2025-02-01",
                "endDate": null,
                "status": "scheduled",
                "createdAt": "2025-01-06T00:48:11+00:00",
                "updatedAt": "2025-01-07T22:19:57+00:00",
                "balanceType": "capped",
                "spendType": "Onsite",
                "privateMarketBillingType": "notApplicable"
            }
        }
    ]
}

Sample response - Versions 2026.07onward

{
  "metadata": {
    "totalItemsAcrossAllPages": 135,
    "currentPageSize": 25,
    "currentPageIndex": 0,
    "totalPages": 6
  },
  "data": [
    {
      "id": "100000000000000001",
      "type": "BalanceV1",
      "attributes": {
        "name": "Sample Name",
        "retailerPoNumber": null,
        "criteoPoNumber": "PO-CRITEO-123",
        "retailerId": null,
        "memo": "Sample memo",
        "deposited": 10.0,
        "spent": 10.0,
        "remaining": 0.0,
        "startDate": "2020-04-13",
        "endDate": null,
        "status": "ended",
        "createdAt": "2020-04-13T15:39:48+00:00",
        "updatedAt": "2023-06-13T13:35:53+00:00",
        "balanceType": "capped",
        "spendType": "onsite",
        "privateMarketBillingType": "notApplicable"
      }
    },
    {
      "id": "100000000000000002",
      "type": "BalanceV1",
      "attributes": {
        "name": "Sample Name",
        "retailerPoNumber": "PO-RETAILER-123",
        "criteoPoNumber": "PO-CRITEO-123",
        "retailerId": 123,
        "memo": "Sample memo",
        "deposited": 100.0,
        "spent": 0.16,
        "remaining": 99.84,
        "startDate": "2026-03-24",
        "endDate": null,
        "status": "active",
        "createdAt": "2026-03-24T18:15:58+00:00",
        "updatedAt": "2026-05-20T17:17:40+00:00",
        "balanceType": "capped",
        "spendType": "Onsite",
        "privateMarketBillingType": "notApplicable"
      }
    }
  ],
  "warnings": [],
  "errors": []
}

Get Specific Balance

Retrieves the balance details of one specific balance belonging to an account.

Returns a single balance including the retailer scoping fields. The poNumber field present on prior API versions will be removed in 2026-07.