balances created through the API will, automatically, be denoted asbillByRetailer
only balances denoted asbillByRetailercan be modified through the API
Writeable? N / Nullable? N
*Required for Balance creation
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.
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.Sample Request
curl -X GET "https://api.criteo.com/{version}/retail-media/accounts/18446744073709551616/balances?pageIndex=0&pageSize=25" \ -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
This endpoint modifies the metadata of a specified balance, like name, poNumber, startDate or endDate. To modify deposited funds, check the following endpoint.
Only Balances created through the API can be modified through this endpoint, ie, with billing type billByRetailer
Sample Request
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": "2025-04-01", "poNumber": "PO 12345", "memo": "Balance for campaigns in 2025 Q1 (with start and end date)" } } }'
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 ResponseResponse Body Parameters
Attribute
Data Type
Description
id
string
CampaignID, respective to the campaign(s) currently appended to the balance
Accepted values: string of int64
Writeable? N / Nullable? N
Sample Request
curl -X GET "https://api.criteo.com/{version}/retail-media/balances/14094543095747588032/campaigns?pageIndex=0&pageSize=25" \ -H "Authorization: Bearer <MY_ACCESS_TOKEN>"
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.Request Body Parameters
Attribute
Data Type
Description
id
string
CampaignID, required to define to which campaign(s) the balance should be appended or deleted
This endpoint removes one or more campaigns from the specified balance. The resulting state of the balance is returned as a single page.Request Body Parameters
Attribute
Data Type
Description
id
string
CampaignID, required to define to which campaign(s) the balance should be appended or deleted
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.Additional query parameter limitToChangeTypes can be used to inform a comma-separated list of changeType values.
Modified UsersmodifiedByUser - 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.
Review the value of field xyz provided in the request
🔴400
Change data capture type xxx is not supported
Change data capture type xxx is not supported
The value oflimitToChangeTypesis not supported for/balances/{balanceId} /history
ensure to use a comma-separated list of available
changeTypevalues defined above
🔴400
Invalid name
Balance name should be unique. There exists balance with the specified name. Balance creation/update has been canceled
Check value ofnamein 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
🔴400
Invalid deltaamount
Can not decrease funds to less than zero
Review value ofdeltaAmountand make sure it’s greater than current balance’sdeposited * (-1)
🔴400
Invalid operation
Can only change the field xxx of a balance not billed by retailer.
Cannot edit balances not created through the API; only balances with billing typebillByRetailercan be modified
🔴400
Invalid operation
Can not add funds to a balance not billed by retailer.
Cannot edit balances not created through the API; only balances with billing typebillByRetailercan be modified
🔴403
Authorization error
Resource access forbidden: does not have permissions
One of the permission levels was not respected. Make sure that the respective API app has access to:
Read/Manage the domain “Balance” (depending on the requested action). Review the Types of Permissions inAuthorization Requests
