Campaigns Endpoints

These endpoints are available in the stable Retail Media API. We recommend using Retail Media 2026.07 instead of the experimental version. In your API calls, replace /experimental/ with /2026-07/, or /2027-01/ for Release Candidates. Learn more about our versioning policy.

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 the details object matching the type.

The objective and the budget belong to the details object, not to the campaign root. A SponsoredProducts campaign sets its own objective; an OnsiteDisplay campaign created through this endpoint is always an impressions campaign, so it sets no objective and its budget is required.

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.
`regulatedCategory`	string	No	Regulated category the campaign advertises. `None` or `Alcohol`.
`scheduleDetails`	object	Yes	Active period of the campaign. Both campaign types own their flight dates and require it.
`sponsoredProductsDetails`	object	No	Objective and budget of a `SponsoredProducts` campaign.
`onsiteDisplayDetails`	object	No	Budget of an `OnsiteDisplay` 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.

A manual SponsoredProducts campaign that runs indefinitely sends exactly 9999-12-30T00:00:00Z as its endDate. Any other far-future date, including a neighbouring one, is treated as a real end date. An objective other than Manual spends its budget over a flight, so it needs a real end date and rejects that value. An OnsiteDisplay Auction campaign rejects it too.

Attribute	Type	Required	Description
`objective`	string	No	What the campaign optimizes for. `Manual`, `Clicks`, `Conversion` or `Revenue`. Defaults to `Manual`.
`budget`	object	No	Financial intent of the campaign. Required for an objective other than `Manual`, which also restricts it to an amount. A manual campaign may cap its own periods and pace its daily spend.

Onsite Display details attributes

Nested under onsiteDisplayDetails.

Attribute	Type	Required	Description
`budget`	object	Yes	Financial intent of the campaign. An amount only: per-period cappings and pacing apply to manual `SponsoredProducts` campaigns.

Budget attributes

Attribute	Type	Required	Description
`amount`	number	No	Total the campaign may spend over its flight. Must be greater than zero. Required unless the campaign is a manual `SponsoredProducts` one, which may leave its total uncapped.
`cappings`	array	No	Manual `SponsoredProducts` campaigns only. Per-period ceilings, at most one entry per period.
`cappings[].type`	string	Yes	Period the ceiling applies to. `Daily` or `Monthly`.
`cappings[].amount`	number	Yes	Ceiling for the period.
`pacing`	object	No	Manual `SponsoredProducts` campaigns only. Asks the platform to spread the budget rather than cap it per period.
`pacing.type`	string	Yes	`Automatic`.

Automatic pacing sets the daily amount itself, so it cannot be combined with a Daily capping.

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"],
        "scheduleDetails": {
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "sponsoredProductsDetails": {
          "objective": "Conversion",
          "budget": {
            "amount": 5000.0
          }
        }
      }
    }
  }'

An OnsiteDisplay campaign carries its budget under onsiteDisplayDetails and sets no objective. Its budget is an amount only:

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"],
        "scheduleDetails": {
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "onsiteDisplayDetails": {
          "budget": { "amount": 5000.0 }
        }
      }
    }
  }'

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.

The details object carries the stored budget back, with amount and, for a manual SponsoredProducts campaign, the cappings and pacing it holds. Only capped periods are reported. The details object that does not match the campaign type is returned as null.

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"],
      "regulatedCategory": "None",
      "scheduleDetails": {
        "startDate": "2026-09-01T00:00:00Z",
        "endDate": "2026-09-30T23:59:59Z"
      },
      "sponsoredProductsDetails": {
        "objective": "Conversion",
        "budget": {
          "amount": 5000.0
        }
      },
      "onsiteDisplayDetails": null
    }
  }
}

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`	`campaign-name-already-exists`	Another campaign in the account already uses this name.
`400 Bad Request`	`json-serialization-error`	A value is outside its enum, for example an unsupported `campaignType`, `buyType` or `objective`.
`400 Bad Request`	`invalid-objective-campaign-type`	The objective is not accepted for the campaign type.
`400 Bad Request`	`invalid-objective-buy-type`	An automatic objective was set without the `Auction` buy type.
`400 Bad Request`	`missing-flight-dates`	`scheduleDetails` is absent.
`400 Bad Request`	`invalid-date-range`	The start date is after the end date.
`400 Bad Request`	`invalid-cd-flight-dates`	An `OnsiteDisplay` `Auction` campaign was given the indefinite end date `9999-12-30T00:00:00Z`.
`400 Bad Request`	`manual-objective-refuses-budget`	A budget was supplied for a manual `OnsiteDisplay` campaign.
`400 Bad Request`	`objective-requires-budget`	An objective other than `Manual` was set without a budget.
`400 Bad Request`	`dynamic-objective-requires-end-date`	An objective other than `Manual` was given the indefinite end date `9999-12-30T00:00:00Z`. It spends its budget over a flight, so it needs a real one.
`400 Bad Request`	`dynamic-objective-budget-is-amount-only`	Cappings or pacing were supplied for an objective other than `Manual`.
`400 Bad Request`	`missing-budget-amount`	The budget carries no amount.
`400 Bad Request`	`invalid-budget-amount`	The budget amount is not greater than zero.
`400 Bad Request`	`invalid-budget-capping-amount`	A capping amount is not greater than zero.
`400 Bad Request`	`duplicate-budget-capping`	The budget carries more than one capping for the same period.
`400 Bad Request`	`invalid-budget-pacing`	Automatic pacing was combined with a `Daily` capping.
`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.
`403 Forbidden`	`forbidden`	The account, or a referenced drawable balance, 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

Sponsored Products details attributes

Onsite Display details attributes

Budget attributes

Sample request

Response attributes

Sample response

Responses

​Overview

​Endpoints Overview

​Create a Campaign

​Path parameter

​Request attributes

​Attribution settings attributes

​Schedule details attributes

​Sponsored Products details attributes

​Onsite Display details attributes

​Budget attributes

​Sample request

​Response attributes

​Sample response

​Responses

Overview

Endpoints Overview

Create a Campaign

Path parameter

Request attributes

Attribution settings attributes

Schedule details attributes

Sponsored Products details attributes

Onsite Display details attributes

Budget attributes

Sample request

Response attributes

Sample response

Responses