Skip to main content
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

​
id
string
Balance IDValues: int64
​
name
string
required
The name of the balanceValues: string
​
retailerPoNumber
string
Retailer-assigned purchase order number. Replaces the former poNumber field.Values: string, nullable
​
deposited
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
​
spent
number
The total lifetime spend on this balanceValues: Amount of funds already spent
​
remaining
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
​
startDate
date
required
The balance start date in the account timeZone if not setValues: YYYY-MM-DD
​
endDate
object
Balance end date in the account timeZone, wrapped in a Nillable object to allow explicit clearing.Shape: { "value": "YYYY-MM-DD" | null }
ValueBehavior
Field omittedNo 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.
​
status
enum
The current balance statusValues: active, scheduled, ended, unknown
​
createdAt
timestamp
Timestamp in UTC of balance creationValues: ISO-8601
​
updatedAt
timestamp
Timestamp in UTC of balance updatedValues: ISO-8601
​
balanceType
enum
required
Type of balanceValues: capped, uncapped
​
spendType
enum
required
The type of balance that will be used based on the campaign typeValues: onsite,offsite
​
memo
string
An optional memo note that can be set on that balanceValues: string value
​
privateMarketBillingType
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": []
}