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

# Balance Management

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>;
};

The balance management endpoints are additional sets of balance apps that allow users to have more control of their balances, along with the existing balance endpoints, which help to link existing balances to a campaign. Balance management will provide flexibility to create and update balances. Balance managing also provides additional `POST` and `PATCH` endpoints to provide the ability to edit specific balance attributes, depending on the end-user access level.

***

<Note>
  **Learn more about campaign management with our API [**here**](/retail-media/v2026-preview/docs/balances)!**
</Note>

## Endpoints

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </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>
          Get All Balances
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Get 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
        </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 funds to an existing balance
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Change a balance dates
        </p>
      </td>
    </tr>

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

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

      <td>
        <p>
          Update balance fields without changing the funds
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Balance response attributes

<ParamField path="id" type="string">
  Balance ID

  **Values:** int64
</ParamField>

<ParamField path="name" type="string" required>
  The name of the balance

  **Values:** string
</ParamField>

<ParamField path="retailerPoNumber" type="string">
  Retailer-assigned purchase order number. Replaces the former `poNumber` field.

  **Values:** string, nullable
</ParamField>

<ParamField path="deposited" type="decimal">
  The amount of billable funds allotted to the balance. The amount should be based on the currency types of an account that the balance link to. User may want to confirm currency with their account settings.For uncapped budgets pass `null` as the deposited amount.

  **Values:** decimal value or `null` for uncapped balances
</ParamField>

<ParamField path="spent" type="number">
  The total lifetime spend on this balance

  **Values:** Amount of funds already spent
</ParamField>

<ParamField path="remaining" type="number">
  Amount of funds remaining until the balance cap is hit. The balance will return a `null` value if no funds have been used.

  **Values:** between 0 and `deposited`
</ParamField>

<ParamField path="startDate" type="date" required>
  The balance start date in the [account](/retail-media/docs/accounts-endpoints) timeZone if not set

  **Values:** YYYY-MM-DD
</ParamField>

<ParamField path="endDate" type="object">
  Balance end date in the [account](/retail-media/docs/accounts-endpoints) timeZone, wrapped in a Nillable object to allow explicit clearing.

  **Shape:** `{ "value": "YYYY-MM-DD" | null }`

  | Value                       | Behavior                                       |
  | --------------------------- | ---------------------------------------------- |
  | Field omitted               | No change applied                              |
  | `{ "value": "2026-12-31" }` | Updates the end date                           |
  | `{ "value": null }`         | Explicitly clears the end date (no expiration) |

  <Warning>
    Sending `{ "value": null }` actively clears the end date. This is different from omitting the field entirely, which leaves the existing value unchanged.
  </Warning>
</ParamField>

<ParamField path="status" type="enum">
  The current balance status

  **Values:** `active`, `scheduled`, `ended`, `unknown`
</ParamField>

<ParamField path="createdAt" type="timestamp">
  Timestamp in UTC of balance creation

  **Values:** ISO-8601
</ParamField>

<ParamField path="updatedAt" type="timestamp">
  Timestamp in UTC of balance updated

  **Values:** ISO-8601
</ParamField>

<ParamField path="balanceType" type="enum" required>
  Type of balance

  **Values:** `capped`, `uncapped`
</ParamField>

<ParamField path="spendType" type="enum" required>
  The type of balance that will be used based on the campaign type

  **Values:** `onsite`,`offsite`
</ParamField>

<ParamField path="memo" type="string">
  An optional memo note that can be set on that balance

  **Values:** string value
</ParamField>

<ParamField path="privateMarketBillingType" type="string">
  Computed value that defines whether the balance will be billed by the retailer or by Criteo.

  **Values:** `billByRetailer`, `billByCriteo`
</ParamField>

***

## Get all balances

This endpoint lists all balances in an account.  Response results will be provided in paginated form.

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

**Sample Request**

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

**Sample Response**

```json expandable theme={null}
{
    "metadata": {
        "totalItemsAcrossAllPages": 54,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 3,
        "nextPage": "https://api.criteo.com/preview/retail-media/accounts/4/balances?pageIndex=1&pageSize=25"
    },
    "data": [
        {
            "attributes": {
                "name": "Balance A",
                "retailerPoNumber": "",
                "memo": "Spring marketing balance",
                "deposited": 10.00000000,
                "spent": 10.00000000,
                "remaining": 0.00000000,
                "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": "billByRetailer",
                "id": "3"
            },
            "id": "3",
            "type": "BalanceResponse"
        },
        // ...
        {
            "attributes": {
                "name": "Balance B",
                "retailerPoNumber": "",
                "memo": "Winter marketing balance",
                "deposited": 0.01000000,
                "spent": 0.00000000,
                "remaining": 0.01000000,
                "startDate": "2022-06-30",
                "endDate": "2022-07-08",
                "status": "ended",
                "createdAt": "2022-06-30T23:51:15+00:00",
                "updatedAt": "2022-06-30T23:51:15+00:00",
                "balanceType": "capped",
                "spendType": "Onsite",
                "privateMarketBillingType": "billByRetailer",
                "id": "330495533735960576"
            },
            "id": "330495533735960576",
            "type": "BalanceResponse"
        }
    ],
    "warnings": [],
    "errors": []
}
```

***

## 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/preview/retail-media/accounts/{accountId}/balances/{balanceId}
  ```
</EndpointBadge>

**Sample Request**

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

**Sample Response**

```json theme={null}
{
    "data": {
        "attributes": {
            "name": "Balance A",
            "retailerPoNumber": "",
            "memo": "Trade marketing balance for spring 2020",
            "deposited": 10.00000000,
            "spent": 10.00000000,
            "remaining": 0.00000000,
            "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": "billByRetailer",
            "id": "3"
        },
        "id": "3",
        "type": "BalanceResponse"
    },
    "warnings": [],
    "errors": []
}
```

***

## Create a new account balance

The endpoint allows you to create a new account balance

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

**Sample Request**

```bash theme={null}
curl -L 'https://api.criteo.com/preview/retail-media/accounts/4/balances' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
	"data": {
		"attributes": {
			"name": "Balance C - API",
			"deposited": "100",
			"startDate": "2023-08-01",
			"endDate": "2023-08-29",
			"spendType": "onsite",
			"memo": "My API balance",
			"retailerPoNumber": "123"
		},
		"id": "4",
		"type": "RetailMediaBalanceCreation"
	}
}'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "attributes": {
            "name": "Balance C - API",
            "retailerPoNumber": "123",
            "memo": "My API balance",
            "deposited": 100.00000000,
            "spent": 0.00000000,
            "remaining": 100.00000000,
            "startDate": "2023-08-01",
            "endDate": "2023-08-29",
            "status": "active",
            "createdAt": "2023-08-04T19:43:15+00:00",
            "updatedAt": "2023-08-04T19:43:15+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer",
            "id": "475388270283501568"
        },
        "id": "475388270283501568",
        "type": "BalanceResponse"
    },
    "warnings": [],
    "errors": []
}
```

***

## Readjust funds for an existing balance

Adjust an existing balance funds without changing other balance attributes.

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

**Sample Request**

In the example below, the call requests a \$10 deduction from an existing balance. The original balance was \$100, and after the call, the new balance amount is now \$90. To remove funds from a balance set the `deltaAmount` to a negative number, whereas set a positive amount to add funds.

```bash theme={null}
curl -L 'https://api.criteo.com/preview/retail-media/accounts/4/balances/475388270283501568/add-funds' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
	"data": {
		"attributes": {
			"deltaAmount": "-10",
			"memo": "Balance re-adjustment. Removing $10 from balance",
			"retailerPoNumber": "123456"
		},
		"id": "475388270283501568",
		"type": "<string>"
	}
}'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "attributes": {
            "name": "Balance C - API",
            "retailerPoNumber": "123456",
            "memo": "Balance re-adjustment. Removing $10 from balance",
            "deposited": 90.00000000,
            "spent": 0.00000000,
            "remaining": 90.00000000,
            "startDate": "2023-08-01",
            "endDate": "2023-08-29",
            "status": "active",
            "createdAt": "2023-08-04T19:43:15+00:00",
            "updatedAt": "2023-08-07T15:43:59+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer",
            "id": "475388270283501568"
        },
        "id": "475388270283501568",
        "type": "BalanceResponse"
    },
    "warnings": [],
    "errors": []
}
```

***

## Change balance dates

Update a balance dates without changing all other balance attributes. The endpoint can be used for scenarios with users with limited permissions to make adjustments to a balance.

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

**Sample Request**

```bash theme={null}
curl -L 'https://api.criteo.com/preview/retail-media/accounts/4/balances/475388270283501568/change-dates' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
	"data": {
		"attributes": {
			"startDate": "2023-08-01",
			"endDate": "2023-08-07",
			"memo": "Updating the balance start and end dates"
		},
		"id": "475388270283501568",
		"type": "RetailMediaBalanceUpdate"
	}
}'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "attributes": {
            "name": "Balance C - API",
            "retailerPoNumber": "123456",
            "memo": "Updating the balance start and end dates",
            "deposited": 90.00000000,
            "spent": 0.00000000,
            "remaining": 90.00000000,
            "startDate": "2023-08-01",
            "endDate": "2023-08-07",
            "status": "active",
            "createdAt": "2023-08-04T19:43:15+00:00",
            "updatedAt": "2023-08-07T16:06:51+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer",
            "id": "475388270283501568"
        },
        "id": "475388270283501568",
        "type": "BalanceResponse"
    },
    "warnings": [],
    "errors": []
}
```

***

## Update balance fields without changing the funds

Update all balance fields without changing the balance funds. The endpoint can be used for scenarios with users with limited permissions to make adjustments to a balance.

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

**Sample Request**

```bash theme={null}
curl -L -X PATCH 'https://api.criteo.com/preview/retail-media/accounts/4/balances/475388270283501568' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
	"data": {
		"attributes": {
			"name": "Balance ABC",
			"retailerPoNumber": "65432",
			"startDate": "2023-08-01",
			"endDate": { "value": "2023-08-07" },
			"memo": "Updating balance without changing the funds"
		},
		"id": "475388270283501568",
		"type": "RetailMediaBalanceUpdate"
	}
}'
```

**Sample Response**

```json theme={null}
{
    "data": {
        "attributes": {
            "name": "Balance ABC",
            "retailerPoNumber": "65432",
            "memo": "Updating balance without changing the funds",
            "deposited": 90.00000000,
            "spent": 0.00000000,
            "remaining": 90.00000000,
            "startDate": "2023-08-01",
            "endDate": "2023-08-07",
            "status": "active",
            "createdAt": "2023-08-04T19:43:15+00:00",
            "updatedAt": "2023-08-07T16:08:40+00:00",
            "balanceType": "capped",
            "spendType": "Onsite",
            "privateMarketBillingType": "billByRetailer",
            "id": "475388270283501568"
        },
        "id": "475388270283501568",
        "type": "BalanceResponse"
    },
    "warnings": [],
    "errors": []
}
```