Campaigns Endpoints

Endpoints

Method	Endpoint	Description
Create a new campaign for the specified account.
Retrieve all campaigns associated with the specified account.
Retrieve details of a specific campaign by its ID.
Update details of a specific campaign by its ID.

Create Operations:

When using the POST method to create a resource, all Required fields must be included. Any Optional fields that are omitted will be set to their default values.

Update Operations:

When using the PUT method to update a resource, all Write fields can be specified. Omitting any of these fields is treated as setting them to null, where applicable.

Campaign Attributes

Attribute	Data Type	Description
Campaign ID, generated internally by Criteo Accepted values: int64 Writeable? N / Nullable? N
Accepted values: int64 Writeable? N / Nullable? N
Accepted values: up to 255-chars string Writeable? Y / Nullable? N
Campaign type If the attribute is passed in the call, a value must be specified Writeable? Y / Nullable? N
Note that preferred campaign types cannot have budgets as these campaign types must be uncapped Accepted values: equals/greater than zero Writeable? Y / Nullable? Y
Amount the campaign has already spent Accepted values: equals/greater than zero Writeable? N / Nullable? N
Writeable? N / Nullable? Y
Accepted values: list of strings Default: empty list Writeable? N / Nullable? N
Post-click attribution window Writeable? Y / Nullable? N
Post-view attribution window Writeable? Y / Nullable? N
Post-click attribution scope Writeable? Y / Nullable? N
Post-view attribution scope Writeable? Y / Nullable? N
Default: empty list Writeable? Y / Nullable? N
Writeable? N / Nullable? N
The maximum monthly spend allowed for the campaign in the currency of the account. The spend is constrained by remaining account balance and total budget of the campaign. Monthly budget spend reset monthly at the start of the month based on the account timezone Writeable? Y / Nullable? Y
Writeable? Y / Nullable? Y
Writeable? Y / Nullable? N
Campaign start date. The campaign starts inactive if invalid start date is not today or end date is in previous day. Default: creation timestamp Writeable? Y / Nullable? Y
Campaign end date. The campaign starts inactive if invalid start date is not today or end date is in previous day Writeable? Y / Nullable? Y
Timestamp of campaign creation, in UTC Writeable? N / Nullable? N
Timestamp of last campaign update, in UTC Writeable? N / Nullable? N
This optional field, exclusively accessible to marketplaces within the European Union (in compliance with the Digital Service Act - DSA), will display the name of the company associated with the advertisement. Accepted values: up to 255-chars string Writeable? Y / Nullable? Y
Accepted values: up to 255-chars string Writeable? Y / Nullable? Y
The retailer this campaign is associated with. Required when using a retailer budget balance. Writeable? Y (at create) / Nullable? Y (for non-retailer-budget campaigns)

(*) Required for create operations

Digital Service Act (DSA)

In compliance with the Digital Services Act (DSA), marketplaces within the European Union will receive information about the company name associated with each advertisement.

Create a Campaign

This endpoint creates a Sponsored Products (type: auction) or Onsite Display (type: preferred) campaign. Retailer budget vs Criteo budget: Including retailerId in the request creates a retailer budget campaign. Omitting retailerId (or setting it to null) creates a standard Criteo budget campaign — retailerId will be null in the response. Balance mapping at create time: You may optionally include drawableBalanceIds to map the campaign to one or more retailer budget balances at creation. All compatibility rules apply (same retailer, same billing type, same demand account). You can also map balances separately after creation using POST /balances/{balanceId}/campaigns/append.

Note on 403 vs 400A 403 on campaign create means the retailerId you set is not recognized as an authorized retailer for your account. A 400 with a specific mismatch code means the retailer is valid but incompatible with the balance you included (see Error responses).Legacy version behavior (2025-10 and earlier): Returns 400 when attempting to create a retailer budget campaign.

Retailer Budgets CampaignsWhen creating a campaign for a retailer-budget balance, retailerId must be provided and must match the retailerId of the balance. Mismatched values will return a RetailerMismatchWithBalance error. Learn more about Retailer budgets here.

Sample Request

cURL

curl -L -X POST 'https://api.criteo.com/2026-01/retail-media/accounts/{accountId}/campaigns' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
    "type": "Campaign",
    "attributes": {
      "name": "My Retailer Budget Campaign",
      "type": "auction",
      "retailerId": "123",
      "drawableBalanceIds": ["100000000000000001"],
      "startDate": "2026-06-01T00:00:00+00:00",
      "clickAttributionWindow": "30D",
      "viewAttributionWindow": "none",
      "clickAttributionScope": "sameSkuCategory",
      "viewAttributionScope": "sameSkuCategory",
      "isAutoDailyPacing": false
    }
  }
}'

Sample Response

{
  "data": {
    "id": "100000000000000001",
    "type": "RetailMediaCampaignV202301",
    "attributes": {
      "accountId": "123",
      "promotedBrandIds": [],
      "budgetSpent": 0.0,
      "budgetRemaining": null,
      "status": "inactive",
      "createdAt": "2026-05-29T20:33:27+00:00",
      "updatedAt": "2026-05-29T20:33:27+00:00",
      "type": "auction",
      "drawableBalanceIds": ["100000000000000001"],
      "clickAttributionWindow": "30D",
      "viewAttributionWindow": "none",
      "retailerId": 123,
      "name": "My Retailer Budget Campaign",
      "budget": null,
      "monthlyPacing": null,
      "dailyPacing": null,
      "isAutoDailyPacing": false,
      "startDate": "2026-06-01T00:00:00+00:00",
      "endDate": null,
      "clickAttributionScope": "sameSkuCategory",
      "viewAttributionScope": "sameSkuCategory",
      "companyName": null,
      "onBehalfCompanyName": null
    }
  }
}

Get All Campaigns by Account ID

This endpoint returns all campaigns for an account.

As of 2026-01, retailerId is included in each campaign’s attributes. Use the retailerId query parameter to filter campaigns by retailer.Legacy version behavior (2025-10 and earlier): Retailer budget campaigns are not returned; retailerId is not present in the attribute set.

Results are paginated using pageIndex and pageSize query parameters; if omitted, defaults to 0 and 25, respectively. See API Response. Sample Request

cURL

curl -L -X GET 'https://api.criteo.com/2026-01/retail-media/accounts/{accountId}/campaigns' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "metadata": {
        "totalItemsAcrossAllPages": 2533,
        "currentPageSize": 2,
        "currentPageIndex": 8,
        "totalPages": 153,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 102
    },
    "data": [
        {
            "id": "100000000000000001",
            "type": "RetailMediaCampaignV202301",
            "attributes": {
                "accountId": "123",
                "promotedBrandIds": [],
                "budgetSpent": 0.0,
                "budgetRemaining": null,
                "status": "inactive",
                "createdAt": "2026-05-29T20:00:47+00:00",
                "updatedAt": "2026-05-29T20:00:47+00:00",
                "type": "auction",
                "drawableBalanceIds": ["100000000000000002"],
                "clickAttributionWindow": "30D",
         	      "viewAttributionWindow": "none",
                "retailerId": 123,
                "name": "Sample Name",
                "budget": null,
                "monthlyPacing": null,
                "dailyPacing": null,
                "isAutoDailyPacing": false,
                "startDate": "2026-06-01T00:00:00+00:00",
                "endDate": null,
                "clickAttributionScope": "sameSkuCategory",
                "viewAttributionScope": "sameSkuCategory",
                "companyName": null,
                "onBehalfCompanyName": null
            }
        }
    ]
}

Get a Specific Campaign

This endpoint retrieves the specified campaign.

As of 2026-07, retailerId is included in the response attributes. Retailer budget campaigns also surface criteoPoNumber and retailerPoNumber from the mapped balance.Legacy version behavior (2026-01 and earlier): Returns 400 for retailer budget campaigns.

Sample Request

cURL

curl -L -X GET 'https://api.criteo.com/{version}/retail-media/campaigns/{campaignId}' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>'

Sample Response

{
    "data": {
        "id": "100000000000000001",
    "type": "RetailMediaCampaignV202301",
    "attributes": {
      "accountId": "123",
      "promotedBrandIds": [],
      "budgetSpent": 0.0,
      "budgetRemaining": null,
      "status": "inactive",
      "createdAt": "2026-05-29T20:00:47+00:00",
      "updatedAt": "2026-05-29T20:00:47+00:00",
      "type": "auction",
      "drawableBalanceIds": ["100000000000000002"],
      "clickAttributionWindow": "30D",
      "viewAttributionWindow": "none",
      "retailerId": 123,
      "name": "Sample Name",
      "budget": null,
      "isAutoDailyPacing": false,
      "startDate": "2026-06-01T00:00:00+00:00",
      "endDate": null,
      "clickAttributionScope": "sameSkuCategory",
      "viewAttributionScope": "sameSkuCategory",
      "companyName": null,
      "onBehalfCompanyName": null
    }
  }
}

Update a Specific Campaign

This endpoint allows you to update a specified campaign. The following example demonstrates how to switch to an uncapped campaign budget and modify the post-view attribution window.

Legacy version behavior (2025-10 and earlier): Returns 400 for retailer budget campaigns.

Sample Request

cURL

curl -L -X PUT 'https://api.criteo.com/2026-01/retail-media/campaigns/{campaignId}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
-d '{
  "data": {
    "type": "Campaign",
    "attributes": {
      "name": "Updated Campaign Name",
      "endDate": "2026-12-31T23:59:59+00:00"
    }
  }
}'

Sample Response

{
  "data": {
    "id": "100000000000000001",
    "type": "RetailMediaCampaignV202301",
    "attributes": {
      "accountId": "123",
      "promotedBrandIds": [],
      "budgetSpent": 0.0,
      "budgetRemaining": null,
      "status": "inactive",
      "createdAt": "2026-05-29T20:00:47+00:00",
      "updatedAt": "2026-05-29T20:00:47+00:00",
      "type": "auction",
      "drawableBalanceIds": ["100000000000000002"],
      "clickAttributionWindow": "30D",
      "viewAttributionWindow": "none",
      "retailerId": 123,
      "name": "Sample Name",
      "budget": null,
      "isAutoDailyPacing": false,
      "startDate": "2026-06-01T00:00:00+00:00",
      "endDate": null,
      "clickAttributionScope": "sameSkuCategory",
      "viewAttributionScope": "sameSkuCategory",
      "companyName": null,
      "onBehalfCompanyName": null
    }
  }
}

Responses

All validation errors on campaign create use code: "validation-error".The error type is identified by a bracketed prefix in the title field.

Status	Title	Description
🟢 `200`		Call completed with success
🟢 `201`		Campaign was created successfully
🔴 `400`	`[retailer-id-mismatch]`	The `retailerId` on the campaign doesn’t match the `retailerId` on one of the balances in `drawableBalanceIds`. Also returned when balances from multiple retailers are included.
🔴 `400`	`[balance-type-mismatch]`	Billing type mismatch — e.g. retailer budget campaign with a Criteo budget balance.
🔴 `400`	`[account-mismatch]`	The balance in `drawableBalanceIds` belongs to a different demand account than the campaign being created.
🔴 `403`	`authorization-unknown`	The `retailerId` in the request is not recognized as an authorized retailer for this account. Use `GET /retailers/search` to discover eligible retailers first.
🔴 `400`	Invalid `isAutoDailyPacing`	Cannot turn on `IsAutoDailyPacing` and add a `DailyPacing` value. `IsAutoDailyPacing` and `Daily Pacing` cannot be active at the same time.
🔴 `400`	Invalid `Budget`	Budget is not allowed for the Preferred campaign.
🔴 `400`	`RetailerMismatchWithBalance`	Campaign `retailerId` does not match the balance `retailerId`. Ensure the `retailerId` in campaign settings matches the `retailerId` on the balance you are associating.
🔴 `400`	`BillingTypeMismatchWithBalance`	The billing type on the campaign doesn’t match the billing type on the balance.
🔴 `400`	`AccountMismatchWithBalance`	The balance in `drawableBalanceIds` does not belong to the request account.
🔴 `400`	`RetailerMismatchWithCampaign`	The line item `targetRetailerId` does not match the campaign’s `retailerId`.

Introduction

Guides for Retail Media API

Endpoints

Campaign Attributes

Digital Service Act (DSA)

Create a Campaign

Get All Campaigns by Account ID

Get a Specific Campaign

Update a Specific Campaign

Responses

​Endpoints

​Campaign Attributes

​Digital Service Act (DSA)

​Create a Campaign

​Get All Campaigns by Account ID

​Get a Specific Campaign

​Update a Specific Campaign

​Responses

Endpoints

Campaign Attributes

Digital Service Act (DSA)

Create a Campaign

Get All Campaigns by Account ID

Get a Specific Campaign

Update a Specific Campaign

Responses