## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://developers.criteo.com/llms.txt)

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

**Getting Started**Learn more about balances [here](https://developers.criteo.com/retail-media/docs/balances#/).

**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](https://developers.criteo.com/retail-media/docs/retailer-budgets).

## 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<br>Accepted values: string of int64<br>Writeable? N / Nullable? N |
| `name`* | `string` | Balance name<br>Accepted values: up to 255-char strings<br>Writeable? Y / Nullable? N |
| `deposited` | `decimal` | Amount of funds deposited; uncapped if`null`<br>Accepted values:`deposited`≥ 0.0<br>Writeable? Y / Nullable? Y |
| `spent` | `decimal` | Amount of funds already spent<br>Accepted values: 0 ≤`spent`≤`deposited`<br>Writeable? N / Nullable? N |
| `remaining` | `decimal` | Amount of funds remaining<br>Accepted values: 0 ≤`remaining`≤`deposited` (or`null`, if`deposited`not set)<br>Writeable? N / Nullable? Y |
| `startDate`* | `timestamp` | Balance start date; if time zone is not set, will consider [Account](https://developers.criteo.com/retail-media/docs/account)‘s time zone as default<br>Accepted values:`yyyy-mm-dd` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html))<br>Writeable? Y / Nullable? N |
| `endDate` | `timestamp` | Balance end date; if time zone is not set, will consider [Account](https://developers.criteo.com/retail-media/docs/account)‘s time zone as default<br>Accepted values:`yyyy-mm-dd` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html))<br>Default: if`null` or absent, balance will be available indefinitely<br>Writeable? Y / Nullable? Y |
| `status` | `enum` | Balance current status<br>Accepted values:`active`, `scheduled`, `ended`, `unknown`<br>Writeable? N / Nullable? N |
| `createdAt` | `timestamp` | Timestamp of balance creation, in UTC<br>Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html))<br>Writeable? N / Nullable? N |
| `updatedAt` | `timestamp` | Timestamp of last balance update, in UTC<br>Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html))<br>Writeable? N / Nullable? N |
| `memo` | `string` | An optional memo note that can be set in the balance<br>Accepted values: up to 250-char strings<br>Writeable? Y / Nullable? Y |
| `balanceType` | `enum` | The balance type is computed based on the deposited amount:<br>Accepted values:`capped`, `uncapped`, `unknown`<br>Writeable? N / Nullable? N<br>- `capped`: if the deposited amount is provided.<br>- `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<br>Accepted values:`Onsite`, `Offsite`, `OffsiteAwareness`<br>Writeable? N / Nullable? N |
| `privateMarketBillingType` | `enum` | Billing type of the balance<br>Accepted values:`notApplicable`, `billByRetailer`, `billByCriteo`<br>⚠️ **Note**:<br>- balances created through the API will, automatically, be denoted as`billByRetailer`<br>- only balances denoted as`billByRetailer`can be modified through the API<br>- `billByCriteo`are balances created in our Commerce Max platform and can only be edited in our UI<br>- `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`.<br>Writeable? N / Nullable? N |
| `retailerId` | `string` | Retailer this balance is scoped to.<br>Present only on retailer budgets.<br>Nullable? Y (null for balances without retailer budgets) |
| `retailerPoNumber` | `string?` | Retailer purchase order number. **Replaces** the removed`poNumber`field.<br>Nullable? Y |
| `criteoPoNumber` | `string?` | Criteo purchase order number.<br>**Replaces** the removed`poNumber`field.<br>Nullable? Y |
| `poNumber` | `string` | Purchase order number.<br>**Removed since 2026.01** and replaced by`retailerPoNumber`and`criteoPoNumber`<br>Accepted values: up to 32-char strings<br>Writeable? Y / Nullable? Y |

*\*Required for Balance creation*

## Balance History Parameters

| Attribute | Data Type | Description |
| --- | --- | --- |
| `dateOfModification` | `timestamp` | Timestamp of balance update<br>Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm` (in [ISO-8601](https://www.iso.org/iso-8601-date-and-time-format.html))<br>Writeable? N / Nullable? N |
| `modifiedByUser` | `string` | Username who modified the insertion order<br>Accepted values: strings in format “j.doe”<br>Writeable? N / Nullable? N |
| `changeType` | `enum` | Definition of the type of change in a balance<br>Accepted values: `BalanceCreated`, `BalanceCapped`, `BalanceUncapped`, `EndDate`, `StartDate`, `RetailerPoNumber`, `ValueAdd`<br>- `BalanceCreated`: new balance is created<br>- `BalanceUncapped`: capped balance is changed to uncapped<br>- `BalanceCapped`: uncapped balance is changed to capped<br>- `StartDate`: start date is modified<br>- `EndDate`: end date is modified |
| `changeDetails` | `object` | Structure with the change details (from Balance History endpoint)<br>Parameters:<br>- `previousValue`: previous value of a property of the balance<br>- `currentValue`: current value of a property of the balance<br>- `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](https://developers.criteo.com/criteo-apis/docs/api-response#pagination).

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](https://developers.criteo.com/retail-media/docs/retailer-billed).**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.07`onward**

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