> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances Endpoints

export const EndpointBadge = ({method = "GET", children}) => {
  const METHOD_STYLES = {
    GET: {
      bg: "mint-bg-[#2AB673]"
    },
    POST: {
      bg: "mint-bg-[#3064E3]"
    },
    PUT: {
      bg: "mint-bg-[#C28C30]"
    },
    PATCH: {
      bg: "mint-bg-[#DA622B]"
    },
    DELETE: {
      bg: "mint-bg-[#CB3A32]"
    },
    API: {
      bg: "mint-bg-black"
    }
  };
  const key = method.toUpperCase();
  const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
  return <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

<Info>
  **Getting Started**

  Learn more about Balances in our Stable version [here](/retail-media/docs/balances#/).
</Info>

***

## Endpoints

<table>
  <thead>
    <tr>
      <th>
        <p>
          Method
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/balances
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve all balances associated with a specific account.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/balances/\{balanceId}
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve a specific balance
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/balances
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a new balance for a specified account.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            PATCH
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/balances/\{balanceId}
          </code>
        </p>
      </td>

      <td>
        <p>
          Modify balance's metadata (name, start/end date - for deposited funds, see below)
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/balances/\{balanceId}/add-funds
          </code>
        </p>
      </td>

      <td>
        <p>
          Add/remove funds deposited in a specific balance.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /balances/\{balanceId}/campaigns
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve all campaigns linked to a specific balance.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /balances/\{balanceId}/campaigns/append
          </code>
        </p>
      </td>

      <td>
        <p>
          Add campaigns to a specific balance.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /balances/\{balanceId}/campaigns/delete
          </code>
        </p>
      </td>

      <td>
        <p>
          Remove campaigns from a specific balance.
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            GET
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /balances/\{balanceId}/history
          </code>
        </p>
      </td>

      <td>
        <p>
          Retrieve all changes made historically to a balance
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Balance Parameters

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Balance ID
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            name
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Balance name
        </p>

        <p>
          Accepted values: up to 255-char strings
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            poNumber
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Purchase order number
        </p>

        <p>
          Accepted values: up to 32-char strings
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            deposited
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            decimal
          </code>
        </p>
      </td>

      <td>
        <p>
          Amount of funds deposited; uncapped if

          <code>
            null
          </code>
        </p>

        <p>
          Accepted values:

          <code>
            deposited
          </code>

          ≥ 0.0
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            spent
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            decimal
          </code>
        </p>
      </td>

      <td>
        <p>
          Amount of funds already spent
        </p>

        <p>
          Accepted values: 0 ≤

          <code>
            spent
          </code>

          ≤

          <code>
            deposited
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            remaining
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            decimal
          </code>
        </p>
      </td>

      <td>
        <p>
          Amount of funds already spent
        </p>

        <p>
          Accepted values: 0 ≤

          <code>
            remaining
          </code>

          ≤

          <code>
            deposited
          </code>

          (or

          <code>
            null
          </code>

          , if

          <code>
            deposited
          </code>

          not set)
        </p>

        <p>
          Writeable? N / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            startDate
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          <code>
            timestamp
          </code>
        </p>
      </td>

      <td>
        <p>
          Balance start date; if time zone is not set, will consider

          <a href="/retail-media/v2026-preview/docs/account">
            Account
          </a>

          's time zone as default
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-dd
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? Y / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            endDate
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            timestamp
          </code>
        </p>
      </td>

      <td>
        <p>
          Balance end date; if time zone is not set, will consider

          <a href="/retail-media/v2026-preview/docs/account">
            Account
          </a>

          's time zone as default
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-dd
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Default: if

          <code>
            null
          </code>

          or absent, balance will be available indefinitely
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            status
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            enum
          </code>
        </p>
      </td>

      <td>
        <p>
          Balance current status
        </p>

        <p>
          Accepted values:

          <code>
            active
          </code>

          ,

          <code>
            scheduled
          </code>

          ,

          <code>
            ended
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            createdAt
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            timestamp
          </code>
        </p>
      </td>

      <td>
        <p>
          Timestamp of balance creation, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            updatedAt
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            timestamp
          </code>
        </p>
      </td>

      <td>
        <p>
          Timestamp of last balance update, in UTC
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            memo
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          An optional memo note that can be set in the balance
        </p>

        <p>
          Accepted values: up to 250-char strings
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            balanceType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            enum
          </code>
        </p>
      </td>

      <td>
        <p>
          The balance type is computed based on the deposited amount:
        </p>

        <p>
          Accepted values:

          <code>
            capped
          </code>

          ,

          <code>
            uncapped
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>

        <ul>
          <li>
            <code>
              capped
            </code>

            : if the deposited amount is provided.
          </li>

          <li>
            <code>
              uncapped
            </code>

            : when there is no amount defined (set to

            <code>
              null
            </code>

            )
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            spendType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            enum
          </code>
        </p>
      </td>

      <td>
        <p>
          The type of balance that will be used based on the campaign type
        </p>

        <p>
          Accepted values:

          <code>
            Onsite
          </code>

          ,

          <code>
            Offsite
          </code>

          ,

          <code>
            OffsiteAwareness
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            privateMarketBillingType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            enum
          </code>
        </p>
      </td>

      <td>
        <p>
          Billing type of the balance
        </p>

        <p>
          Accepted values:

          <code>
            notApplicable
          </code>

          ,

          <code>
            billByRetailer
          </code>

          ,

          <code>
            billByCriteo
          </code>
        </p>

        <p>
          ⚠️

          <b>
            Note
          </b>

          :
        </p>

        <ul>
          <li>
            balances created through the API will, automatically, be denoted as

            <code>
              billByRetailer
            </code>
          </li>

          <li>
            only balances denoted as

            <code>
              billByRetailer
            </code>

            can be modified through the API
          </li>
        </ul>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

*\*Required for Balance creation*

<Info>
  **Field Definitions**

  * **Writeable (Y/N)**: Indicates if the field can be modified in requests.
  * **Nullable (Y/N)**: Indicates if the field can accept null/empty values.
  * **Primary Key**: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., `retailerId`, `campaignId`, `lineItemId`) and are usually required in the URL path.
</Info>

***

## Balance History Parameters

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            dateOfModification
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            timestamp
          </code>
        </p>
      </td>

      <td>
        <p>
          Timestamp of balance update
        </p>

        <p>
          Accepted values:

          <code>
            yyyy-mm-ddThh:mm:ss±hh:mm
          </code>

          (in

          <a href="https://www.iso.org/iso-8601-date-and-time-format.html">
            ISO-8601
          </a>

          )
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            modifiedByUser
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          Username who modified the insertion order
        </p>

        <p>
          Accepted values: strings in format "j.doe"
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            changeType
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            enum
          </code>
        </p>
      </td>

      <td>
        <p>
          Definition of the type of change in a balance
        </p>

        <p>
          Accepted values:
        </p>

        <ul>
          <li>
            <code>
              BalanceCreated
            </code>

            : new balance is created
          </li>

          <li>
            <code>
              BalanceAdded
            </code>

            : capped balance amount was increased by a certain amount
          </li>

          <li>
            <code>
              BalanceRemoved
            </code>

            : capped balance is decreased by a certain amount
          </li>

          <li>
            <code>
              BalanceUncapped
            </code>

            : capped balance is changed to uncapped
          </li>

          <li>
            <code>
              BalanceCapped
            </code>

            : uncapped balance is changed to capped
          </li>

          <li>
            <code>
              StartDate
            </code>

            : start date is modified
          </li>

          <li>
            <code>
              EndDate
            </code>

            : end date is modified
          </li>

          <li>
            <code>
              BalanceName
            </code>

            : balance name is modified
          </li>

          <li>
            <code>
              PoNumber
            </code>

            : PO Number is modified
          </li>

          <li>
            <code>
              ValueAdd
            </code>

            : new additional amount is added to the balance
          </li>

          <li>
            <code>
              SalesforceId
            </code>

            : SalesForceID (internal Criteo ID) is modified by Criteo (this would appear for Criteo billed balances)
          </li>
        </ul>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            changeDetails
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            object
          </code>
        </p>
      </td>

      <td>
        <p>
          Structure with the change details (from Balance History endpoint)
        </p>

        <p>
          Parameters:
        </p>

        <ul>
          <li>
            <code>
              previousValue
            </code>

            : previous value of a property of the balance
          </li>

          <li>
            <code>
              currentValue
            </code>

            : current value of a property of the balance
          </li>

          <li>
            <code>
              changeValue
            </code>

            : change value of a property of the balance
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

***

## Get all Balances

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](/retail-media/v2026-preview/docs/api-response#pagination).

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/balances
  ```
</EndpointBadge>

**Sample Request**

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

  ```python Python theme={null}
  import requests

  url = "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=0&pageSize=25"

  payload={}
  headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("text/plain");

  RequestBody body = RequestBody.create(mediaType, "");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=0&pageSize=25")
    .method("GET", body)
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=0&pageSize=25');
  $request->setMethod(HTTP_Request2::METHOD_GET);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
      echo $response->getBody();
    }
    
    else {
      echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
      $response->getReasonPhrase();
    }
  }

  catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
  }
  ```
</CodeGroup>

**Sample Response**

```json expandable theme={null}
{
    "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"
            }
        }
    ]
}
```

***

## Get specific balance

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

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/balances/{balanceId}
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -L 'https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/4237496305219757554' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "id": "4237496305219757554",
        "type": "BalanceResponseV2",
        "attributes": {
            "name": "Balance 789",
            "poNumber": "",
            "memo": "10k for the special 2s-day promotion",
            "deposited": 10000.0,
            "spent": 923.4,
            "remaining": 9076.6,
            "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"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## Create a new account Balance

This endpoint creates a new balance in the specified account.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/balances
  ```
</EndpointBadge>

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X POST 'https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
      -d '{
              "data": {
                  "attributes": {
                      "name": "Balance 2025 Q1",
                      "startDate": "2025-01-01",
                      "spendType": "Onsite",
                      "poNumber": null,
                      "deposited": 12500.00,
                      "endDate": "",
                      "memo": "Balance for campaigns in 2025 Q1"
                  }
              }
          }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances"

  payload = json.dumps({
      "data": {
          "attributes": {
              "name": "Balance 2025 Q1",
              "startDate": "2025-01-01",
              "spendType": "Onsite",
              "poNumber": None,
              "deposited": 12500.00,
              "endDate": "",
              "memo": "Balance for campaigns in 2025 Q1"
          }
      }
  })
  headers = {
      'Accept': 'application/json',
      'Content-Type': 'application/json',
      'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("application/json");

  RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"name\":\"Balance 2025 Q1\",\"startDate\":\"2025-01-01\",\"spendType\":\"Onsite\",\"poNumber\": null,\"deposited\": 12500.00,\"endDate\":\"\",\"memo\":\"Balance for campaigns in 2025 Q1\"}}}");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
      'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
      'Content-Type' => 'application/json',
      'Accept' => 'application/json',
      'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));
  $request->setBody('{"data":{"attributes":{"name":"Balance 2025 Q1","startDate":"2025-01-01","spendType":"Onsite","poNumber":null,"deposited":12500.00,"endDate":"","memo":"Balance for campaigns in 2025 Q1"}}');
  try{
      $response = $request->send();
      if ($response->getStatus() == 200) {
          echo $response->getBody();
      }
      else {
          echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
          $response->getReasonPhrase();
      }
  }
  catch(HTTP_Request2_Exception $e) {
      echo 'Error: ' . $e->getMessage();
  }

  ```
</CodeGroup>

**Sample Response**

```json theme={null}
{
    "id": "697385288434028544",
    "type": "BalanceResponseV2",
    "data": {
        "attributes": {
            "name": "Balance 2025 Q1",
            "poNumber": null,
            "memo": "Balance for campaigns in 2025 Q1",
            "deposited": 12500.00,
            "spent": 0.00,
            "remaining": 12500.00,
            "startDate": "2025-01-01",
            "endDate": null,
            "status": "active",
            "createdAt": "2025-04-08T10:00:09+00:00",
            "updatedAt": "2025-04-08T10:00:09+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## Modify Balance Metadata

This endpoint modifies the metadata of a specified balance, like `name`, `poNumber`, `startDate` or `endDate`. To modify deposited funds, check the following endpoint.

<Info>
  **End Date Behavior**

  The `endDate` attribute now supports explicitly removing an end date from a balance. You can now provide `endDate` as an object containing a value field. If `endDate` is omitted from the request, the existing value will remain unchanged.

  This allows balances to be converted from fixed date ranges to open-ended balances when required for advertiser or retailer workflows.
</Info>

<Info>
  Only Balances created through the API can be modified through this endpoint, i.e., with billing type `billByRetailer`
</Info>

<EndpointBadge method="patch">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/balances/{balanceId}
  ```
</EndpointBadge>

**Sample Request**

With a defined `endDate`

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X PATCH 'https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
      -d '{
              "data": {
                  "attributes": {
                      "startDate": "2025-01-01",
          						"endDate": {
            							"value": "2026-04-01"
          								}
        							},
                      "poNumber": "PO 12345",
                      "memo": "Balance for campaigns in 2025 Q1 (with start and end date)"
                  }
              }
          }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544"

  payload = json.dumps({
      "data": {
          "attributes": {
              "startDate": "2025-01-01",
              "endDate": "2025-04-01",
              "poNumber": "PO 12345",
              "memo": "Balance for campaigns in 2025 Q1 (with start and end date)"
          }
      }
  })
  headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("PATCH", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("application/json");

  RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"startDate\":\"2025-01-01\",\"endDate\":\"2025-04-01\",\"poNumber\":\"PO 12345\",\"memo\":\"Balance for campaigns in 2025 Q1 (with start and end date)\"}}}");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544")
    .method("PATCH", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
      'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
      'Content-Type' => 'application/json',
      'Accept' => 'application/json',
      'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));
  $request->setBody('{"data":{"attributes":{"startDate":"2025-01-01","endDate":"2025-04-01","poNumber":"PO 12345","memo":"Balance for campaigns in 2025 Q1 (with start and end date)"}}}');
  try{
      $response = $request->send();
      if ($response->getStatus() == 200) {
          echo $response->getBody();
      }
      else {
          echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
          $response->getReasonPhrase();
      }
  }
  catch(HTTP_Request2_Exception $e) {
      echo 'Error: ' . $e->getMessage();
  }

  ```
</CodeGroup>

With a `null`value for `endDate`:

```bash theme={null}
curl -L -X PATCH 'https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": {
      "attributes": {
        "endDate": {
          "value": null
        }
      },
      "id": "677963427765682176",
      "type": "UpdateBalanceV2"
    }
  }'

```

**Sample Response**

With a defined `endDate`:

```json theme={null}
{
    "id": "697385288434028544",
    "type": "BalanceResponseV2",
    "data": {
        "attributes": {
            "name": "Balance 2025 Q1",
            "poNumber": "PO 12345",
            "memo": "Balance for campaigns in 2025 Q1 (with start and end date)",
            "deposited": 12500.00,
            "spent": 0.00,
            "remaining": 12500.00,
            "startDate": "2025-01-01",
            "endDate": "2025-04-01",
            "status": "active",
            "createdAt": "2025-04-08T10:00:09+00:00",
            "updatedAt": "2025-04-08T10:00:09+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer"
        }
    },
    "warnings": [],
    "errors": []
}
```

With a `null` value for `endDate`:

```json theme={null}
{
    "data": {
        "id": "677963427765682176",
        "type": "BalanceResponseV1",
        "attributes": {
            "name": "test balance aakchn 2.13.25",
            "poNumber": "",
            "memo": "test do not bill",
            "deposited": 5.00,
            "spent": 0.00,
            "remaining": 5.00,
            "startDate": "2025-02-13",
            "endDate": null,
            "status": "active",
            "createdAt": "2025-02-13T19:44:37+00:00",
            "updatedAt": "2026-02-05T21:35:04+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## Add or Remove Balance Funds

This endpoint allows adding or removing funds deposited in a specific balance.

<Info>
  Only Balances created through the API can be modified through this endpoint, ie, with billing type `billByRetailer`
</Info>

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/balances/{balanceId}/add-funds
  ```
</EndpointBadge>

**Request Body Parameters**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            deltaAmount
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          <code>
            decimal
          </code>
        </p>
      </td>

      <td>
        <p>
          Difference amount of fund to be added/removed from balance; it cannot reduce the current amount of funds deposited to less than zero
        </p>

        <p>
          Accepted values:

          <code>
            deltaAmount
          </code>

          ≥

          <code>
            deposited \* (-1)
          </code>
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            poNumber
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          New purchase order number
        </p>

        <p>
          Accepted values: up to 32-char strings
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            memo
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          A memo note that should be set in the balance together with this modification
        </p>

        <p>
          Accepted values: up to 250-char strings
        </p>

        <p>
          Writeable? Y / Nullable? Y
        </p>
      </td>
    </tr>
  </tbody>
</table>

*\*Required*

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -L -X PATCH 'https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544/add-funds' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
      -d '{
              "data": {
                  "attributes": {
                      "deltaAmount": -2500.00,
                      "poNumber": "PO 12346",
                      "memo": "Reduced balance for campaigns in 2025 Q1"
                  }
              }
          }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544/add-funds"

  payload = json.dumps({
      "data": {
          "attributes": {
              "deltaAmount": -2500.00,
              "poNumber": "PO 12346",
              "memo": "Reduced balance for campaigns in 2025 Q1"
          }
      }
  })
  headers = {
      'Content-Type': 'application/json',
      'Accept': 'application/json',
      'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)

  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("application/json");

  RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"deltaAmount\": -2500.00,\"poNumber\":\"PO 12346",\"memo":\"Reduced balance for campaigns in 2025 Q1\"}}}");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544/add-funds")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances/697385288434028544/add-funds');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
      'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
      'Content-Type' => 'application/json',
      'Accept' => 'application/json',
      'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));
  $request->setBody('{"data":{"attributes":{"deltaAmount":-2500.00,"poNumber":"PO 12346","memo":"Reduced balance for campaigns in 2025 Q1"}}}');
  try{
      $response = $request->send();
      if ($response->getStatus() == 200) {
          echo $response->getBody();
      }
      else {
          echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
          $response->getReasonPhrase();
      }
  }
  catch(HTTP_Request2_Exception $e) {
      echo 'Error: ' . $e->getMessage();
  }
  ```
</CodeGroup>

**Sample Response**

```json theme={null}
{
    "id": "697385288434028544",
    "type": "BalanceResponseV2",
    "data": {
        "attributes": {
            "name": "Balance 2025 Q1",
            "poNumber": "PO 12346",
            "memo": "Reduced balance for campaigns in 2025 Q1",
            "deposited": 10000.00,
            "spent": 0.00,
            "remaining": 10000.00,
            "startDate": "2025-01-01",
            "endDate": "2025-04-01",
            "status": "active",
            "createdAt": "2025-04-08T10:00:09+00:00",
            "updatedAt": "2025-04-08T10:00:09+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer"
        }
    },
    "warnings": [],
    "errors": []
}
```

***

## Get all Campaigns on a specific Balance

This endpoint lists all campaigns on the specified balance.

Results are paginated using `pageIndex` and `pageSize` query parameters; if omitted, defaults to `0` and `25`, respective - see [API Response](/retail-media/v2026-preview/docs/api-response)

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/balances/{balanceId}/campaigns
  ```
</EndpointBadge>

**Response Body Parameters**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          <a href="/retail-media/v2025.07/docs/campaign">
            Campaign
          </a>

          ID, respective to the campaign(s) currently appended to the balance
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns?pageIndex=0&pageSize=25" \
      -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("text/plain");

  RequestBody body = RequestBody.create(mediaType, "");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns?pageIndex=0&pageSize=25")
    .method("GET", body)
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns?pageIndex=0&pageSize=25"

  payload={}
  headers = {
    'Accept': 'application/json',
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("GET", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns?pageIndex=0&pageSize=25');
  $request->setMethod(HTTP_Request2::METHOD_GET);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));
  $request->setHeader(array(
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
      echo $response->getBody();
    }
    
    else {
      echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
      $response->getReasonPhrase();
    }
  }

  catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
  }
  ```
</CodeGroup>

**Sample Response**

```json theme={null}
{
    "data": [
        {
            "id": "8343086999167541140",
            "type": "RetailMediaCampaign"
        },
        {
            "id": "3683145960016759663",
            "type": "RetailMediaCampaign"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 2,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}
```

***

## Add Campaigns to a specific Balance

This endpoint adds one or more campaigns to the specified balance. The results are provided in a single page. In this example, a campaign had already existed on the balance before two new additions.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/balances/{balanceId}/campaigns/append
  ```
</EndpointBadge>

**Request Body Parameters**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          <a href="/retail-media/v2025.07/docs/campaign">
            Campaign
          </a>

          ID, required to define to which campaign(s) the balance should be appended or deleted
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/append" \
      -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
              "data": [
                  {
                      "id": "3683145960016759663",
                      "type": "RetailMediaCampaign"
                  },
                  {
                      "id": "16108177282234788969",
                      "type": "RetailMediaCampaign"
                  }
              ]
          }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/append"

  payload = json.dumps({
    "data": [
      {
        "id": "3683145960016759663",
        "type": "RetailMediaCampaign"
      },
      {
        "id": "16108177282234788969",
        "type": "RetailMediaCampaign"
      }
    ]
  })
  headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("application/json");

  RequestBody body = RequestBody.create(mediaType, "{\"data\":[{\"id\":\"3683145960016759663\",\"type\":\"RetailMediaCampaign\"},{\"id\":\"16108177282234788969\",\"type\":\"RetailMediaCampaign\"}]\n}");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/append")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/append');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));

  $request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  $request->setBody('{"data":[{"id":"3683145960016759663","type":"RetailMediaCampaign"},{"id":"16108177282234788969","type":"RetailMediaCampaign"}]}');
  try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
      echo $response->getBody();
    }
    
    else {
      echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
      $response->getReasonPhrase();
    }
  }
  catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
  }
  ```
</CodeGroup>

**Sample Response**

```json theme={null}
{
    "data": [
        {
            "id": "8343086999167541140",
            "type": "RetailMediaCampaign"
        },
        {
            "id": "3683145960016759663",
            "type": "RetailMediaCampaign"
        },
        {
            "id": "16108177282234788969",
            "type": "RetailMediaCampaign"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 3,
        "currentPageSize": 3,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}
```

***

## Remove Campaigns from a specific Balance

This endpoint removes one or more campaigns from the specified balance. The resulting state of the balance is returned as a single page.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/balances/{balanceId}/campaigns/delete
  ```
</EndpointBadge>

**Request Body Parameters**

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>
        </p>
      </td>

      <td>
        <p>
          <code>
            string
          </code>
        </p>
      </td>

      <td>
        <p>
          <a href="/retail-media/v2025.07/docs/campaign">
            Campaign
          </a>

          ID, required to define to which campaign(s) the balance should be appended or deleted
        </p>

        <p>
          Accepted values: string of int64
        </p>

        <p>
          Writeable? N / Nullable? N
        </p>
      </td>
    </tr>
  </tbody>
</table>

**Sample Request**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/delete" \
      -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
      -H "Content-Type: application/json" \
      -d '{
              "data": [
                  {
                      "id": "16108177282234788969",
                      "type": "RetailMediaCampaign"
                  }
              ]
          }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/delete"

  payload = json.dumps({
    "data": [
      {
        "id": "16108177282234788969",
        "type": "RetailMediaCampaign"
      }
    ]
  })
  headers = {
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Authorization': 'Bearer <MY_ACCESS_TOKEN>'
  }

  response = requests.request("POST", url, headers=headers, data=payload)

  print(response.text)
  ```

  ```java Java theme={null}
  OkHttpClient client = new OkHttpClient().newBuilder()
    .build();

  MediaType mediaType = MediaType.parse("application/json");

  RequestBody body = RequestBody.create(mediaType, "{\"data\":[{\"id\":\"16108177282234788969\",\"type\":\"RetailMediaCampaign\"}]}");

  Request request = new Request.Builder()
    .url("https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/delete")
    .method("POST", body)
    .addHeader("Content-Type", "application/json")
    .addHeader("Accept", "application/json")
    .addHeader("Authorization", "Bearer <MY_ACCESS_TOKEN>")
    .build();

  Response response = client.newCall(request).execute();
  ```

  ```php PHP expandable theme={null}
  <?php
  require_once 'HTTP/Request2.php';
  $request = new HTTP_Request2();
  $request->setUrl('https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns/delete');
  $request->setMethod(HTTP_Request2::METHOD_POST);
  $request->setConfig(array(
    'follow_redirects' => TRUE
  ));

  $request->setHeader(array(
    'Content-Type' => 'application/json',
    'Accept' => 'application/json',
    'Authorization' => 'Bearer <MY_ACCESS_TOKEN>'
  ));

  $request->setBody('{"data":[{"id":"16108177282234788969","type":"RetailMediaCampaign"}]}');
  try {
    $response = $request->send();
    if ($response->getStatus() == 200) {
      echo $response->getBody();
    }
    
    else {
      echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
      $response->getReasonPhrase();
    }
  }

  catch(HTTP_Request2_Exception $e) {
    echo 'Error: ' . $e->getMessage();
  }
  ```
</CodeGroup>

**Sample Response**

```json theme={null}
{
    "data": [
        {
            "id": "8343086999167541140",
            "type": "RetailMediaCampaign"
        },
        {
            "id": "3683145960016759663",
            "type": "RetailMediaCampaign"
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 2,
        "currentPageSize": 2,
        "currentPageIndex": 0,
        "totalPages": 1,
        "nextPage": null,
        "previousPage": null
    }
}
```

***

## Get Balance History

This endpoint lists all changes made to a specific balance.

Results are paginated using `offset` and `limit` query parameters; if omitted, defaults to `0` and `500`, respectively. See [API Response](/retail-media/v2026-preview/docs/api-response#pagination).

Additional query parameter `limitToChangeTypes` can be used to inform a comma-separated list of `changeType` values.

<Info>
  **Modified Users**

  `modifiedByUser` - When a balance is updated via Criteo's Retail Media UI, the user login name will be provided. For instance, if “Kip Heaney” updated the balance on 2023-11-07, it indicates that Kip made the change through the Criteo Retail Media UI.

  If a balance is updated through the Criteo API, the name of the API application responsible for the change will be shown. For example, on 2024-03-20, the balance was updated by the API application **Retail Media API Application.**
</Info>

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/balances/{balanceId}/history
  ```
</EndpointBadge>

**Sample Request**: retrieve all changes

```bash theme={null}
curl -L 'https://api.criteo.com/{version}/retail-media/balances/697385288434028544/history?offset=0&limit=25' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer &lt;TOKEN&gt;'
```

**Sample Response**: retrieve all changes

```json expandable theme={null}
{
    "meta": {
        "count": 5,
        "offset": 0,
        "limit": 25
    },
    "data": [
        {
            "dateOfModification": "2025-02-15T12:24:49-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "BalanceCreated",
            "changeDetails": {
                "previousValue": null,
                "currentValue": "12500.00000000",
                "changeValue": null
            },
            "memo": "Balance for campaigns in 2025 Q1"
        },
        {
            "dateOfModification": "2025-02-15T12:25:40-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "EndDate",
            "changeDetails": {
                "previousValue": null,
                "currentValue": "2025-04-01T23:59:59-04:00",
                "changeValue": null
            },
            "memo": "Balance for campaigns in 2025 Q1 (with start and end date)"
        },
        {
            "dateOfModification": "2025-02-15T12:25:40-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "PoNumber",
            "changeDetails": {
                "previousValue": null,
                "currentValue": "PO 12345",
                "changeValue": null
            },
            "memo": "Balance for campaigns in 2025 Q1 (with start and end date)"
        },
        {
            "dateOfModification": "2025-02-15T12:26:16-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "BalanceRemoved",
            "changeDetails": {
                "previousValue": "12500.00000000",
                "currentValue": "10000.00000000",
                "changeValue": "-2500.00000000"
            },
            "memo": "Reduced balance for campaigns in 2025 Q1"
        },
        {
            "dateOfModification": "2025-02-15T12:26:16-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "PoNumber",
            "changeDetails": {
                "previousValue": "PO 12345",
                "currentValue": "PO 12346",
                "changeValue": null
            },
            "memo": "Reduced balance for campaigns in 2025 Q1"
        }
    ]
}
```

**Sample Request**: retrieve only changes in balance values (added / removed)

```bash theme={null}
curl -L 'https://api.criteo.com/{version}/retail-media/balances/697385288434028544/history?offset=0&limit=25&limitToChangeTypes=BalanceAdded,BalanceRemoved' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer &lt;TOKEN&gt;'
```

**Sample Response**: retrieve only changes in balance values (added / removed)

```json expandable theme={null}
{
    "meta": {
        "count": 2,
        "offset": 0,
        "limit": 25
    },
    "data": [
        {
            "dateOfModification": "2024-02-15T12:10:11.2807153-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "BalanceRemoved",
            "changeDetails": {
                "previousValue": "12500.00000000",
                "currentValue": "10000.00000000",
                "changeValue": "-2500.00000000"
            },
            "memo": "Reduced balance for campaigns in 2025 Q1"
        },
        {
            "dateOfModification": "2024-03-03T16:30:21.2807153-04:00",
            "modifiedByUser": "Retail Media API Application",
            "changeType": "BalanceAdded",
            "changeDetails": {
                "previousValue": "10000.00000000",
                "currentValue": "15000.00000000",
                "changeValue": "5000.00000000"
            },
            "memo": "Increased balance for campaigns in 2025 Q1"
        }
    ]
}
```

***

## Responses

<table>
  <thead>
    <tr>
      <th>
        <p>
          Response
        </p>
      </th>

      <th>
        <p>
          Title
        </p>
      </th>

      <th>
        <p>
          Detail
        </p>
      </th>

      <th>
        <p>
          Troubleshooting
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          🟢

          <code>
            200
          </code>
        </p>
      </td>

      <td />

      <td />

      <td>
        <p>
          Call executed with success
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🟢

          <code>
            201
          </code>
        </p>
      </td>

      <td />

      <td />

      <td>
        <p>
          Balance request created with success
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Error deserializing request
          </b>
        </p>
      </td>

      <td>
        <p>
          Field xyz is not valid
        </p>
      </td>

      <td>
        <p>
          Review the value of field xyz provided in the request
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Change data capture type xxx is not supported
          </b>
        </p>
      </td>

      <td>
        <p>
          Change data capture type xxx is not supported
        </p>
      </td>

      <td>
        <p>
          The value of

          <code>
            limitToChangeTypes
          </code>

          is not supported for

          <code>
            /balances/\{balanceId} /history
          </code>

          * ensure to use a comma-separated list of available

          <code>
            changeType
          </code>

          values defined above
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Invalid name
          </b>
        </p>
      </td>

      <td>
        <p>
          Balance name should be unique. There exists balance with the specified name. Balance creation/update has been canceled
        </p>
      </td>

      <td>
        <p>
          Check value of

          <code>
            name
          </code>

          in the request trying to create/edit a balance. In case of editing, either provided a new name value or omit this parameter to maintain its same value
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Invalid deltaamount
          </b>
        </p>
      </td>

      <td>
        <p>
          Can not decrease funds to less than zero
        </p>
      </td>

      <td>
        <p>
          Review value of

          <code>
            deltaAmount
          </code>

          and make sure it's greater than current balance's

          <code>
            deposited \* (-1)
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Invalid operation
          </b>
        </p>
      </td>

      <td>
        <p>
          Can only change the field xxx of a balance not billed by retailer.
        </p>
      </td>

      <td>
        <p>
          Cannot edit balances not created through the API; only balances with billing type

          <code>
            billByRetailer
          </code>

          can be modified
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Invalid operation
          </b>
        </p>
      </td>

      <td>
        <p>
          Can not add funds to a balance not billed by retailer.
        </p>
      </td>

      <td>
        <p>
          Cannot edit balances not created through the API; only balances with billing type

          <code>
            billByRetailer
          </code>

          can be modified
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            403
          </code>
        </p>
      </td>

      <td>
        <p>
          <b>
            Authorization error
          </b>
        </p>
      </td>

      <td>
        <p>
          Resource access forbidden: does not have permissions
        </p>
      </td>

      <td>
        <p>
          One of the permission levels was not respected. Make sure that the respective API app has access to:
        </p>

        <ul>
          <li>
            Read/Manage the domain "Balance" (depending on the requested action). Review the Types of Permissions in

            <a href="/retail-media/v2026-preview/docs/authorization-requests">
              Authorization Requests
            </a>
          </li>

          <li>
            the

            <code>
              accountId
            </code>

            or

            <code>
              balanceId
            </code>

            provided in the request
          </li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

***

<br />