The poNumber field on balance responses is removed in 2026-01 and replaced by two separate fields: retailerPoNumber and criteoPoNumber. This is a breaking change for consumers of GET /balances on prior versions who rely on poNumber.
All other new fields (retailerId, privateMarketBillingType) are additive. Retailer budgets are hidden by default on prior API versions.
You can learn more about retailer budgets on this page.
balances created through the API will, automatically, be denoted asbillByRetailer
only balances denoted asbillByRetailercan be modified through the API
billByCriteoare balances created in our Commerce Max platform and can only be edited in our UI
notApplicableis an initial or default value if theprivateMarketBillingTypeis not set yet. If it is observed it would be treated as the default valuebillByRetailer.
Writeable? N / Nullable? N
retailerId
string
Retailer this balance is scoped to.
Present only on retailer budgets.
Nullable? Y (null for balances without retailer budgets)
retailerPoNumber
string?
Retailer purchase order number.Replacesthe removedpoNumberfield.
Nullable? Y
criteoPoNumber
string?
Criteo purchase order number.
Replacesthe removedpoNumberfield.
Nullable? Y
poNumber
string
Purchase order number.
Removed since 2026.01and replaced byretailerPoNumberandcriteoPoNumber
Accepted values: up to 32-char strings
Writeable? Y / Nullable? Y
*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.
On API version 2026-07 and later, retailer budgets are included and retailerId, retailerPoNumber, and criteoPoNumber are returned. The old poNumber field is removed.
Learn more on retailer budgets here.Legacy version behavior (2026-01 and earlier): Only standard Criteo budget balances are returned. retailerId, retailerPoNumber, and criteoPoNumber are not present in the response. The legacy poNumber field is present.
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>"
Retrieves the balance details of one specific balances belonging to an account.
Returns a single balance including the retailer scoping fields. The poNumber field present on prior API versions will be removed in 2026-07.Legacy version behavior (2026-01 and earlier): Returns 400 with "This version endpoint doesn't support retailer-sold balance. Use latest version instead." when the requested balance is a retailer budget balance.
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, i.e., with billing type billByRetailer.
Retailer budget balances are read-only via API. Any PATCH request against a retailer budget balance returns 403 regardless of API version.
Balance attributes (dates, PO numbers, amounts) are managed by Criteo on behalf of the retailer.
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.
The API enforces compatibility between the campaigns and the balance — all must share the same billing type, retailer (for retailer budget), and demand account. If any campaign in the request fails validation, the entire request is rejected and no campaigns are mapped.Validation rules:
All campaigns must be retailer budget campaigns when the balance is a retailer budget balance (and vice versa) — otherwise BillingTypeMismatchWithBalance
The retailerId on every campaign must match the balance’s retailerId — otherwise RetailerMismatchWithBalance
All campaigns must belong to the same demand account as the balance — otherwise 403
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.
Retailer BudgetsReturns a chronological list of changes to a balance. PO number updates appear as separate entries keyed by changeType — not as field keys on every entry.Observed changeType values:BalanceCreated, BalanceCapped, BalanceUncapped, EndDate, StartDate, CriteoPoNumber, RetailerPoNumber, ValueAddEach entry’s changeDetails carries:
previousValue — value before the change
currentValue — value after the change
changeValue — delta where applicable (e.g. ValueAdd); null otherwise
Legacy version behavior (2026-01 and earlier): Returns 400 with ”This version endpoint doesn't support retailer-sold balance. Use latest version instead.” when the requested balance is a retailer budget balance.
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
The “append” endpoint uses a different error code from campaign create: code: "campaigns-balance-mapping-validation-error", title: "Validation error".The specific mismatch type is identified by a bracketed prefix in the detail field.
Status
code
detail prefix
Description
🔴400
campaigns-balance-mapping-validation-error
[retailer-id-mismatch]
The retailerId on one or more campaigns in ids doesn’t match the balance’s retailerId. Entire request rejected — no campaigns are mapped.
🔴400
campaigns-balance-mapping-validation-error
[balance-type-mismatch]
Billing type mismatch — e.g. retailer budget campaign appended to a Criteo budget balance, or vice versa. Entire request rejected.
🔴403
—
—
Campaigns in ids belong to a different demand account than the balance.
