Campaigns Endpoints

This endpoint is available in the Experimental version of the Retail Media API only. Experimental endpoints may change without prior notice. See the versioning policy for details.

Overview

A campaign groups line items that share attribution settings, flight dates and budget. campaignType is a required discriminator. The fields are the same for both types. Some accept type-specific values.

`objective`	`SponsoredProducts`	`OnsiteDisplay`
`Clicks`	Yes	-
`Conversion`	Yes	-
`Revenue`	Yes	-
`Impressions`	-	Yes

An objective the campaign type does not accept returns invalid-objective-campaign-type.

Prerequisites

Before calling these endpoints, ensure the following are in place:

Authentication: a valid access token. See Authentication.
App permissions: the RetailMedia_Campaign_Manage scope to create and update, and RetailMedia_Campaign_Read to fetch and search. See App Scopes.

Endpoints

Method	Endpoint	Description
`POST`	`/accounts/{account-id}/campaigns`	Create a campaign.
`GET`	`/campaigns/{campaign-id}`	Fetch a campaign.
`PATCH`	`/campaigns/{campaign-id}`	Update a campaign.
`POST`	`/accounts/{account-id}/campaigns/search`	Search campaigns under an account.

Create a Campaign

Path Parameters

Parameter	Type	Required	Description
`account-id`	string	Yes	Identifier of the account that owns the campaign.

Request Attributes

All attributes below are nested under data.attributes. The resource type is CampaignCreateModel.

Attribute	Type	Required	Description
`name`	string	Yes	Unique within the account. 1 to 255 characters.
`campaignType`	string	Yes	`SponsoredProducts` or `OnsiteDisplay`. Set only on creation.
`buyType`	string	Yes	`Auction`. Set only on creation.
`objective`	string	Yes	See Overview. Set only on creation.
`budgetDetails.amount`	number	Yes	Total the campaign may spend over its flight. Greater than 0.
`scheduleDetails.startDate`	string	Yes	Flight start, as a date-time.
`scheduleDetails.endDate`	string	Yes	Flight end, as a date-time. Not before `startDate`. `9999-12-30T00:00:00Z` is rejected.
`attributionSettings.clickAttributionWindow`	string	No	`OneWeek`, `TwoWeeks` or `OneMonth`. Default: `OneMonth` for `SponsoredProducts`, `TwoWeeks` for `OnsiteDisplay`.
`attributionSettings.viewAttributionWindow`	string	No	`None`, `OneDay`, `OneWeek`, `TwoWeeks` or `OneMonth`. Default: `OneDay` for `SponsoredProducts`, `TwoWeeks` for `OnsiteDisplay`. Not longer than the click window.
`attributionSettings.clickAttributionScope`	string	No	`SameSku`, `SameSkuCategory` or `SameSkuCategoryBrand`. Default: `SameSkuCategory`.
`attributionSettings.viewAttributionScope`	string	No	`SameSku`, `SameSkuCategory` or `SameSkuCategoryBrand`. Default: `SameSku` for `SponsoredProducts`, `SameSkuCategory` for `OnsiteDisplay`. Not broader than the click scope.
`regulatedCategory`	string	No	`None` or `Alcohol`. Default: `None`. Set only on creation.
`drawableBalanceIds`	array of strings	No	Balances the campaign draws from.
`billByRetailerId`	string	No	Retailer billed. Set only on creation.
`companyName`	string	No	EU DSA. Up to 255 characters. Supply accounts only.
`onBehalfCompanyName`	string	No	EU DSA. Up to 255 characters. Supply accounts only.

An unknown or inaccessible balance in drawableBalanceIds fails the request and no campaign is kept. Sample Request

curl -L -X POST 'https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": {
      "type": "CampaignCreateModel",
      "attributes": {
        "name": "Back-to-school sponsored products",
        "campaignType": "SponsoredProducts",
        "buyType": "Auction",
        "objective": "Conversion",
        "budgetDetails": { "amount": 5000 },
        "scheduleDetails": {
          "startDate": "2026-11-02T00:00:00Z",
          "endDate": "2026-12-31T00:00:00Z"
        },
        "drawableBalanceIds": ["1122"]
      }
    }
  }'

Response Attributes

The response is a CampaignResponseModel. See Get a Campaign for the attributes. The budget is the stored one: spent is 0 and remaining equals amount. Sample Response - 201 Created

{
  "data": {
    "id": "987654321",
    "type": "CampaignResponseModel",
    "attributes": {
      "id": "987654321",
      "accountId": "12345",
      "name": "Back-to-school sponsored products",
      "status": "Inactive",
      "campaignType": "SponsoredProducts",
      "buyType": "Auction",
      "objective": "Conversion",
      "budgetDetails": {
        "amount": 5000.0,
        "spent": 0.0,
        "remaining": 5000.0,
        "memo": null,
        "cappings": [],
        "pacing": { "type": "None" },
        "status": "BudgetAvailable"
      },
      "scheduleDetails": {
        "startDate": "2026-11-02T00:00:00+00:00",
        "endDate": "2026-12-31T00:00:00+00:00"
      },
      "attributionSettings": {
        "clickAttributionWindow": "OneMonth",
        "viewAttributionWindow": "OneDay",
        "clickAttributionScope": "SameSkuCategory",
        "viewAttributionScope": "SameSku"
      },
      "drawableBalanceIds": ["1122"],
      "regulatedCategory": "None",
      "companyName": null,
      "onBehalfCompanyName": null,
      "billByRetailerId": null,
      "createdAt": "2026-10-27T12:23:47.9648104+00:00",
      "updatedAt": "2026-10-27T12:23:47.9648104+00:00"
    }
  }
}

Get a Campaign

Path Parameters

Parameter	Type	Required	Description
`campaign-id`	string	Yes	Identifier of the campaign to retrieve.

Response Attributes

All attributes below are nested under data.attributes.

Attribute	Type	Description
`id`	string	Campaign identifier.
`accountId`	string	Account that owns the campaign.
`name`	string	Campaign name.
`status`	string	`Active` when at least one line item is active, otherwise `Inactive`.
`campaignType`	string	`SponsoredProducts` or `OnsiteDisplay`.
`buyType`	string	`Auction`, `PreferredDeals` or `Sponsorship`.
`objective`	string	`Clicks`, `Conversion`, `Revenue` or `Impressions`.
`budgetDetails.amount`	number or null	Total the campaign may spend over its flight. Null when uncapped.
`budgetDetails.spent`	number	Amount spent so far.
`budgetDetails.remaining`	number or null	Amount left under the cap. Null when uncapped.
`budgetDetails.memo`	string or null	Note from the latest budget change.
`budgetDetails.cappings`	array	Per-period ceilings. Only capped periods are reported.
`budgetDetails.pacing.type`	string	`None` or `Automatic`.
`budgetDetails.status`	string	Which cap stops spending: `BudgetAvailable`, `DailyBudgetReached`, `MonthlyBudgetReached` or `TotalBudgetReached`. Omitted when unknown.
`scheduleDetails.startDate`	string	Flight start.
`scheduleDetails.endDate`	string	Flight end.
`attributionSettings`	object	The four attribution settings.
`regulatedCategory`	string	`None` or `Alcohol`.
`drawableBalanceIds`	array of strings	Balances the campaign draws from.
`billByRetailerId`	string or null	Retailer billed.
`companyName`	string or null	EU DSA.
`onBehalfCompanyName`	string or null	EU DSA.
`createdAt`	string	Creation time, UTC.
`updatedAt`	string	Last update time, UTC.

Sample Request

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

Sample Response - 200 OK

{
  "data": {
    "id": "987654321",
    "type": "CampaignResponseModel",
    "attributes": {
      "id": "987654321",
      "accountId": "12345",
      "name": "Back-to-school sponsored products",
      "status": "Active",
      "campaignType": "SponsoredProducts",
      "buyType": "Auction",
      "objective": "Conversion",
      "budgetDetails": {
        "amount": 5000.0,
        "spent": 1250.0,
        "remaining": 3750.0,
        "memo": null,
        "cappings": [],
        "pacing": { "type": "None" },
        "status": "BudgetAvailable"
      },
      "scheduleDetails": {
        "startDate": "2026-11-02T00:00:00+00:00",
        "endDate": "2026-12-31T00:00:00+00:00"
      },
      "attributionSettings": {
        "clickAttributionWindow": "OneMonth",
        "viewAttributionWindow": "OneDay",
        "clickAttributionScope": "SameSkuCategory",
        "viewAttributionScope": "SameSku"
      },
      "drawableBalanceIds": ["1122"],
      "regulatedCategory": "None",
      "companyName": null,
      "onBehalfCompanyName": null,
      "billByRetailerId": null,
      "createdAt": "2026-10-27T12:23:47.9648104+00:00",
      "updatedAt": "2026-10-27T12:23:47.9648104+00:00"
    }
  }
}

Update a Campaign

PATCH is partial: include only the fields you want to change. Omitted fields are left unchanged. A request without fields succeeds and returns the campaign as stored.

Path Parameters

Parameter	Type	Required	Description
`campaign-id`	string	Yes	Identifier of the campaign to update.

Request Attributes

All attributes below are nested under data.attributes. The resource type is CampaignUpdateModel.

Attribute	Type	Required	Description
`name`	string	No	Unique within the account. 1 to 255 characters.
`budgetDetails.amount`	number	Required with `budgetDetails`	New total. Greater than 0.
`budgetDetails.memo`	string	No	Note for the change. Up to 250 characters. An omitted memo clears the stored one.
`scheduleDetails.startDate`	string	Required with `scheduleDetails`	New flight start.
`scheduleDetails.endDate`	string	Required with `scheduleDetails`	New flight end. `9999-12-30T00:00:00Z` is rejected.
`attributionSettings`	object	No	Same fields as on creation. Omitted fields are unchanged. The rules apply to the merged result.
`companyName`	object	No	`{ "value": "..." }` to set, `{ "value": null }` to clear. Supply accounts only.
`onBehalfCompanyName`	object	No	Same as `companyName`.

campaignType, buyType, objective, regulatedCategory, billByRetailerId and drawableBalanceIds are set only on creation and are ignored here. budgetDetails and scheduleDetails sent as null leave the stored values unchanged. An archived campaign cannot be updated. Sample Request

curl -L -X PATCH 'https://api.criteo.com/experimental/retail-media/campaigns/987654321' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": {
      "type": "CampaignUpdateModel",
      "attributes": {
        "name": "Back-to-school sponsored products v2",
        "budgetDetails": { "amount": 8000, "memo": "Raised for peak week" }
      }
    }
  }'

Response Attributes

The response is a CampaignModel. It has the attributes of Get a Campaign, without drawableBalanceIds. Sample Response - 200 OK

{
  "data": {
    "id": "987654321",
    "type": "CampaignModel",
    "attributes": {
      "id": "987654321",
      "accountId": "12345",
      "name": "Back-to-school sponsored products v2",
      "status": "Active",
      "campaignType": "SponsoredProducts",
      "buyType": "Auction",
      "objective": "Conversion",
      "budgetDetails": {
        "amount": 8000.0,
        "spent": 1250.0,
        "remaining": 6750.0,
        "memo": "Raised for peak week",
        "cappings": [],
        "pacing": { "type": "None" },
        "status": "BudgetAvailable"
      },
      "scheduleDetails": {
        "startDate": "2026-11-02T00:00:00+00:00",
        "endDate": "2026-12-31T00:00:00+00:00"
      },
      "attributionSettings": {
        "clickAttributionWindow": "OneMonth",
        "viewAttributionWindow": "OneDay",
        "clickAttributionScope": "SameSkuCategory",
        "viewAttributionScope": "SameSku"
      },
      "regulatedCategory": "None",
      "companyName": null,
      "onBehalfCompanyName": null,
      "billByRetailerId": null,
      "createdAt": "2026-10-27T12:23:47.9648104+00:00",
      "updatedAt": "2026-10-28T09:15:02.1203318+00:00"
    }
  }
}

Search Campaigns

All filters are optional. Values within a filter are ORed. Distinct filters are ANDed.

Path Parameters

Parameter	Type	Required	Description
`account-id`	string	Yes	Identifier of the account to search within.

Request Attributes

All attributes below are nested under data.attributes. The resource type is CampaignSearchModel.

Attribute	Type	Required	Description
`campaignIdFilter`	array of strings	No	Numeric campaign identifiers.
`campaignTypeFilter`	array of strings	No	`SponsoredProducts`, `OnsiteDisplay`.
`buyTypeFilter`	array of strings	No	`Auction`, `PreferredDeals`, `Sponsorship`.
`campaignStatusFilter`	array of strings	No	`Active`, `Inactive`.
`limit`	integer	No	Page size. 1 to 500. Default: 25.
`offset`	integer	No	Matches to skip. Default: 0. `offset + limit` cannot exceed 10000.

Sample Request

curl -L -X POST 'https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns/search' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>' \
  -d '{
    "data": {
      "type": "CampaignSearchModel",
      "attributes": {
        "campaignTypeFilter": ["SponsoredProducts"],
        "campaignStatusFilter": ["Active"],
        "limit": 25,
        "offset": 0
      }
    }
  }'

Response Attributes

data is an array of CampaignResponseModel. See Get a Campaign for the attributes.

Attribute	Type	Description
`metadata.count`	integer	Total matches across all pages.
`metadata.limit`	integer	Page size applied.
`metadata.offset`	integer	Offset applied.

Sample Response - 200 OK

{
  "data": [
    {
      "id": "987654321",
      "type": "CampaignResponseModel",
      "attributes": {
        "id": "987654321",
        "accountId": "12345",
        "name": "Back-to-school sponsored products",
        "status": "Active",
        "campaignType": "SponsoredProducts",
        "buyType": "Auction",
        "objective": "Conversion",
        "budgetDetails": {
          "amount": 5000.0,
          "spent": 1250.0,
          "remaining": 3750.0,
          "memo": null,
          "cappings": [],
          "pacing": { "type": "None" },
          "status": "BudgetAvailable"
        },
        "scheduleDetails": {
          "startDate": "2026-11-02T00:00:00+00:00",
          "endDate": "2026-12-31T00:00:00+00:00"
        },
        "attributionSettings": {
          "clickAttributionWindow": "OneMonth",
          "viewAttributionWindow": "OneDay",
          "clickAttributionScope": "SameSkuCategory",
          "viewAttributionScope": "SameSku"
        },
        "drawableBalanceIds": [],
        "regulatedCategory": "None",
        "companyName": null,
        "onBehalfCompanyName": null,
        "billByRetailerId": null,
        "createdAt": "2026-10-27T12:23:47.9648104+00:00",
        "updatedAt": "2026-10-27T12:23:47.9648104+00:00"
      }
    }
  ],
  "metadata": { "offset": 0, "limit": 25, "count": 1 }
}

Known Limitations

Search budgetDetails comes from a search index and lag a campaign that has just changed. Fetch the campaign for current figures.
drawableBalanceIds is always empty in search results.
The update response does not include drawableBalanceIds.

Error Codes

Code	HTTP Status	When It Occurs
`json-serialization-error`	`400`	A required property is missing or `null`, or an enum value is invalid.
`json-reader-error`	`400`	A value has the wrong type or format.
`bad-request`	`400`	Create: `drawableBalanceIds` contains a non-string.
`request-invalid`	`400`	Create: `billByRetailerId` is not numeric.
`attribute-required`	`400`	Search: the body is present without `data`.
`invalid-pagination`	`400`	Search: `limit` or `offset` is out of range.
`invalid-external-campaign-id`	`400`	Search: a `campaignIdFilter` entry is not numeric.
`invalid-external-account-id`	`400`	Search: `account-id` is not numeric.
`campaign-name-cannot-be-null-or-whitespace`	`400`	The name is blank.
`invalid-name`	`400`	The name exceeds 255 characters.
`campaign-name-already-exists`	`400`	Create: another campaign in the account has this name.
`campaign-name-already-exists`	`409`	Update: another campaign in the account has this name.
`campaign-archived`	`409`	Update: the campaign is archived.
`invalid-objective-campaign-type`	`400`	Create: the campaign type does not accept the objective.
`invalid-budget-amount`	`400`	The budget amount is 0 or negative.
`invalid-budget-memo`	`400`	Update: the memo exceeds 250 characters.
`campaign-budget-rejected`	`400`	The budget was refused. `title` gives the reason.
`dynamic-objective-requires-end-date`	`400`	`endDate` is `9999-12-30T00:00:00Z`.
`invalid-cd-flight-dates`	`400`	Same, for `OnsiteDisplay`. Returned with the code above.
`invalid-date-range`	`400`	`startDate` is after `endDate`.
`click-attribution-window-not-greater-than-view-attribution-window`	`400`	The view window exceeds the click window.
`click-attribution-scope-smaller-than-view-attribution-scope`	`400`	The view scope is broader than the click scope.
`only-supply-can-set-paying-company-name`	`400`	`companyName` is set or cleared on a non-supply account.
`only-supply-can-set-on-behalf`	`400`	`onBehalfCompanyName` is set or cleared on a non-supply account.
`invalid-company-name`	`400`	The company name exceeds 255 characters.
`invalid-on-behalf`	`400`	The on-behalf name exceeds 255 characters.
`not-authorized`	`403`	The account or campaign does not exist, is not numeric, or is not accessible.
`not-authorized`	`403`	Create: `billByRetailerId` is set on an account that cannot use it.
`forbidden`	`403`	Create: a balance in `drawableBalanceIds` does not exist or is not accessible.

Introduction

Guides for Retail Media API

Overview

Prerequisites

Endpoints

Create a Campaign

Path Parameters

Request Attributes

Response Attributes

Get a Campaign

Path Parameters

Response Attributes

Update a Campaign

Path Parameters

Request Attributes

Response Attributes

Search Campaigns

Path Parameters

Request Attributes

Response Attributes

Known Limitations

Error Codes

​Overview

​Prerequisites

​Endpoints

​Create a Campaign

​Path Parameters

​Request Attributes

​Response Attributes

​Get a Campaign

​Path Parameters

​Response Attributes

​Update a Campaign

​Path Parameters

​Request Attributes

​Response Attributes

​Search Campaigns

​Path Parameters

​Request Attributes

​Response Attributes

​Known Limitations

​Error Codes

Overview

Prerequisites

Endpoints

Create a Campaign

Path Parameters

Request Attributes

Response Attributes

Get a Campaign

Path Parameters

Response Attributes

Update a Campaign

Path Parameters

Request Attributes

Response Attributes

Search Campaigns

Path Parameters

Request Attributes

Response Attributes

Known Limitations

Error Codes