Balance Management

The Preview tier is now deprecated following our new versioning policy. You have until the end of 2026 to migrate to either the current stable 2026.07 version or the upcoming release candidate 2027.01, which will be available soon.

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.

Learn more about campaign management with our API here!

Endpoints

Verb	Endpoint	Description
GET	`/accounts/{accountId}/balances`	Get All Balances
GET	`/accounts/{accountId}/balances/{balanceId}`	Get a specific balance
POST	`/accounts/{accountId}/balances`	Create a new balance
POST	`/accounts/{accountId}/balances/{balanceId}/add-funds`	Add funds to an existing balance
POST	`/accounts/{accountId}/balances/{balanceId}/change-dates`	Change a balance dates
PATCH	`/accounts/{accountId}/balances/{balanceId}`	Update balance fields without changing the funds

Balance response attributes

string

Balance IDValues: int64

string

required

The name of the balanceValues: string

string

Retailer-assigned purchase order number. Replaces the former poNumber field.Values: string, nullable

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

number

The total lifetime spend on this balanceValues: Amount of funds already spent

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

date

required

The balance start date in the account timeZone if not setValues: YYYY-MM-DD

object

Balance end date in the account 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)

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

enum

The current balance statusValues: active, scheduled, ended, unknown

timestamp

Timestamp in UTC of balance creationValues: ISO-8601

timestamp

Timestamp in UTC of balance updatedValues: ISO-8601

enum

required

Type of balanceValues: capped, uncapped

enum

required

The type of balance that will be used based on the campaign typeValues: onsite,offsite

string

An optional memo note that can be set on that balanceValues: string value

string

Computed value that defines whether the balance will be billed by the retailer or by Criteo.Values: billByRetailer, billByCriteo

Get all balances

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

curl -L 'https://api.criteo.com/preview/retail-media/accounts/4/balances' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "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 Sample Request

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

{
    "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 Sample Request

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

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

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

{
    "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. Sample Request

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

{
    "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. Sample Request

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

{
    "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": []
}

Introduction

Guides for Retail Media API

Endpoints

Balance response attributes

Get all balances

Get specific balance

Create a new account balance

Readjust funds for an existing balance

Change balance dates

Update balance fields without changing the funds

​Endpoints

​Balance response attributes

​Get all balances

​Get specific balance

​Create a new account balance

​Readjust funds for an existing balance

​Change balance dates

​Update balance fields without changing the funds

Endpoints

Balance response attributes

Get all balances

Get specific balance

Create a new account balance

Readjust funds for an existing balance

Change balance dates

Update balance fields without changing the funds