Campaigns Endpoints

Overview

A campaign groups line items that share attribution settings, flight dates and budget. It is the entity you create first, before adding the line items that control delivery. The campaigns endpoint is shared across campaign types. It exposes common fields through one contract instead of separate Sponsored Products and Onsite Display routes. The campaignType attribute is the discriminator. Type-specific fields are carried in a matching details object alongside the common attributes. Include only the details objects supported by the campaign type.

scheduleDetails and budgetDetails apply to SponsoredProducts campaigns only. OnsiteDisplay campaigns reject them.objective accepts Manual for either type. The automatic objectives Clicks, Conversion and Revenue require a SponsoredProducts campaign with the Auction buy type.

Endpoints Overview

Method	Endpoint	Description
`POST`	`/accounts/{account-id}/campaigns`	Create a campaign under an account.

Create a Campaign

Path parameter

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

The authenticated user must have permission to manage campaigns on the requested account.

Request attributes

All attributes below are nested under data.attributes in the request envelope, and the resource type is CampaignCreateModel.

Attribute	Type	Required	Description
`name`	string	Yes	Display name of the campaign. It must be unique within the account and contain up to 255 characters.
`campaignType`	string	Yes	Type of campaign, set only on creation. `SponsoredProducts` or `OnsiteDisplay`. Determines which details objects are accepted.
`buyType`	string	Yes	Buy type of the campaign, set only on creation. `Auction`.
`attributionSettings`	object	No	Attribution windows and scopes. Each setting may be omitted and is then populated with the default for the campaign type.
`drawableBalanceIds`	array	No	Identifiers of the balances the campaign draws from. Defaults to empty; at least one balance is required before the campaign can start.
`companyName`	string	No	Name of the company associated with the advertisement. Available to European Union marketplaces only, in compliance with the Digital Services Act. Only supply accounts may set it.
`onBehalfCompanyName`	string	No	Name of the company the advertisement runs on behalf of. Available to European Union marketplaces only, in compliance with the Digital Services Act. Only supply accounts may set it.
`billByRetailerId`	string	No	Identifier of the retailer the campaign is billed to, set only on creation. Required when drawing from a retailer budget balance. Only network demand accounts may set it.
`objective`	string	No	Campaign budget allocation control. `Manual` keeps existing behavior; `Clicks`, `Conversion` and `Revenue` activate campaign-level allocation and require a `SponsoredProducts` campaign with the `Auction` buy type. Defaults to `Manual`.
`scheduleDetails`	object	No	`SponsoredProducts` only. Active period of the campaign. `OnsiteDisplay` campaigns reject it.
`budgetDetails`	object	No	`SponsoredProducts` only. Budget and pacing of the campaign.

Attribution settings attributes

Attribute	Type	Required	Description
`clickAttributionWindow`	string	No	`OneWeek`, `TwoWeeks` or `OneMonth`.
`viewAttributionWindow`	string	No	`None`, `OneDay`, `OneWeek`, `TwoWeeks` or `OneMonth`.
`clickAttributionScope`	string	No	`SameSku`, `SameSkuCategory` or `SameSkuCategoryBrand`.
`viewAttributionScope`	string	No	`SameSku`, `SameSkuCategory` or `SameSkuCategoryBrand`.

Defaults applied when a setting is omitted:

Setting	`OnsiteDisplay`	`SponsoredProducts`
`clickAttributionWindow`	`TwoWeeks`	`OneMonth`
`viewAttributionWindow`	`TwoWeeks`	`OneDay`
`clickAttributionScope`	`SameSkuCategory`	`SameSkuCategory`
`viewAttributionScope`	`SameSkuCategory`	`SameSku`

Schedule details attributes

Attribute	Type	Required	Description
`startDate`	string	Yes	Start of the campaign’s active period, as a date-time.
`endDate`	string	Yes	End of the campaign’s active period, as a date-time.

Budget details attributes

Attribute	Type	Required	Description
`budget`	number	No	Total budget of the campaign. Omit for an uncapped budget.
`dailyPacing`	number	No	Maximum spend per day. Omit for uncapped daily spend.
`monthlyPacing`	number	No	Maximum spend per month. Omit for uncapped monthly spend.
`isAutoDailyPacing`	boolean	No	Whether daily spend is paced automatically across the campaign’s active period.

Sample request

curl -X POST "https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns" \
  -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "CampaignCreateModel",
      "attributes": {
        "name": "Back-to-school sponsored products",
        "campaignType": "SponsoredProducts",
        "buyType": "Auction",
        "attributionSettings": {
          "clickAttributionWindow": "OneMonth",
          "viewAttributionWindow": "OneDay",
          "clickAttributionScope": "SameSkuCategory",
          "viewAttributionScope": "SameSku"
        },
        "drawableBalanceIds": ["1122"],
        "objective": "Conversion",
        "scheduleDetails": {
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "budgetDetails": {
          "budget": 5000.0,
          "isAutoDailyPacing": true
        }
      }
    }
  }'

An OnsiteDisplay campaign omits scheduleDetails and budgetDetails:

curl -X POST "https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns" \
  -H "Authorization: Bearer <MY_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "data": {
      "type": "CampaignCreateModel",
      "attributes": {
        "name": "Summer display",
        "campaignType": "OnsiteDisplay",
        "buyType": "Auction",
        "attributionSettings": {
          "clickAttributionWindow": "TwoWeeks",
          "viewAttributionWindow": "TwoWeeks",
          "clickAttributionScope": "SameSkuCategory",
          "viewAttributionScope": "SameSkuCategory"
        },
        "drawableBalanceIds": ["1122"]
      }
    }
  }'

Response attributes

All attributes below are nested under data.attributes in the response envelope, and the resource type is CampaignResponseModel. Alongside the attributes accepted on creation, the response carries:

Attribute	Type	Description
`accountId`	string	Identifier of the account that owns the campaign.
`status`	string	Campaign status, derived from the status of the line items it holds. `Active` when at least one line item is active, otherwise `Inactive`.
`createdAt`	string	When the campaign was created.
`updatedAt`	string	When the campaign was last modified.
`budgetDetails.budgetSpent`	number	Amount spent against the campaign budget.
`budgetDetails.budgetRemaining`	number	Amount left on the campaign budget. Omitted when the budget is uncapped.

Sample response

{
  "data": {
    "id": "987654321",
    "type": "CampaignResponseModel",
    "attributes": {
      "accountId": "12345",
      "name": "Back-to-school sponsored products",
      "campaignType": "SponsoredProducts",
      "buyType": "Auction",
      "status": "Inactive",
      "createdAt": "2026-09-01T10:00:00Z",
      "updatedAt": "2026-09-01T10:00:00Z",
      "attributionSettings": {
        "clickAttributionWindow": "OneMonth",
        "viewAttributionWindow": "OneDay",
        "clickAttributionScope": "SameSkuCategory",
        "viewAttributionScope": "SameSku"
      },
      "companyName": null,
      "onBehalfCompanyName": null,
      "billByRetailerId": null,
      "drawableBalanceIds": ["1122"],
      "objective": "Conversion",
      "scheduleDetails": {
        "startDate": "2026-09-01T00:00:00Z",
        "endDate": "2026-09-30T23:59:59Z"
      },
      "budgetDetails": {
        "budget": 5000.0,
        "dailyPacing": null,
        "monthlyPacing": null,
        "isAutoDailyPacing": true,
        "budgetSpent": 0.0,
        "budgetRemaining": 5000.0
      }
    }
  }
}

Responses

Validation failures return type: validation and a code identifying the rule that rejected the request.

Status	Code	Description
`201 Created`		Returns the created campaign.
`400 Bad Request`	`campaign-name-cannot-be-null-or-whitespace`	The campaign name is missing or blank.
`400 Bad Request`	`invalid-name`	The campaign name exceeds 255 characters.
`400 Bad Request`	`invalid-campaign-type`	The campaign type is not a supported value.
`400 Bad Request`	`invalid-buy-type`	The buy type is not a supported value.
`400 Bad Request`	`invalid-objective`	The objective is not a supported value.
`400 Bad Request`	`invalid-objective-campaign-type`	An automatic objective was set on a campaign that is not `SponsoredProducts`.
`400 Bad Request`	`invalid-objective-buy-type`	An automatic objective was set without the `Auction` buy type.
`400 Bad Request`	`invalid-date-range`	The start date is after the end date.
`400 Bad Request`	`invalid-cd-flight-dates`	`scheduleDetails` was supplied for an `OnsiteDisplay` campaign.
`400 Bad Request`	`invalid-company-name`	The company name exceeds 255 characters.
`400 Bad Request`	`invalid-on-behalf`	The on-behalf company name exceeds 255 characters.
`400 Bad Request`	`only-supply-can-set-paying-company-name`	Only supply accounts can set the company name paying for the ad.
`400 Bad Request`	`only-supply-can-set-on-behalf`	Only supply accounts can set the company name the ad is on behalf of.
`400 Bad Request`	`invalid-retailer-billed-retailer-id`	Only network demand accounts can set `billByRetailerId`.
`400 Bad Request`	`invalid-click-lookback`	The click attribution window is not a supported value.
`400 Bad Request`	`invalid-view-lookback`	The view attribution window is not a supported value.
`400 Bad Request`	`invalid-click-match-level`	The click attribution scope is not a supported value.
`400 Bad Request`	`invalid-view-match-level`	The view attribution scope is not a supported value.
`400 Bad Request`	`click-attribution-window-not-greater-than-view-attribution-window`	The click attribution window is shorter than the view attribution window.
`400 Bad Request`	`click-attribution-scope-smaller-than-view-attribution-scope`	The click attribution scope is narrower than the view attribution scope.
`400 Bad Request`	`bad-request`	`budgetDetails` was supplied for an `OnsiteDisplay` campaign.
`403 Forbidden`		The account does not exist or is not accessible. For security, the response does not identify which condition occurred.

Introduction

Guides for Retail Media API

Overview

Endpoints Overview

Create a Campaign

Path parameter

Request attributes

Attribution settings attributes

Schedule details attributes

Budget details attributes

Sample request

Response attributes

Sample response

Responses

​Overview

​Endpoints Overview

​Create a Campaign

​Path parameter

​Request attributes

​Attribution settings attributes

​Schedule details attributes

​Budget details attributes

​Sample request

​Response attributes

​Sample response

​Responses

Overview

Endpoints Overview

Create a Campaign

Path parameter

Request attributes

Attribution settings attributes

Schedule details attributes

Budget details attributes

Sample request

Response attributes

Sample response

Responses