> ## Documentation Index
> Fetch the complete documentation index at: https://developers.criteo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Campaigns Endpoints
> Create the campaigns that group line items and hold shared settings and budget.
export const EndpointBadge = ({method = "GET", children}) => {
const METHOD_STYLES = {
GET: {
bg: "mint-bg-[#2AB673]"
},
POST: {
bg: "mint-bg-[#3064E3]"
},
PUT: {
bg: "mint-bg-[#C28C30]"
},
PATCH: {
bg: "mint-bg-[#DA622B]"
},
DELETE: {
bg: "mint-bg-[#CB3A32]"
},
API: {
bg: "mint-bg-black"
}
};
const key = method.toUpperCase();
const styles = METHOD_STYLES[key] ?? METHOD_STYLES.API;
return
{key}
{children}
;
};
## 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
```http theme={null}
https://api.criteo.com/experimental/retail-media/accounts/{account-id}/campaigns
```
### 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
```bash theme={null}
curl -X POST "https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns" \
-H "Authorization: Bearer " \
-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`:
```bash theme={null}
curl -X POST "https://api.criteo.com/experimental/retail-media/accounts/12345/campaigns" \
-H "Authorization: Bearer " \
-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
```json theme={null}
{
"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. |