Onsite Display Campaigns

Introduction

Onsite Display Campaigns allow advertisers and retailers to configure and manage auction-based display advertising campaigns across retailer properties.

These campaigns define high-level settings such as attribution, frequency capping, and budget source configuration. Campaigns act as containers for Auction Display Line Items, where execution and delivery logic are defined.

Business Context

Onsite Display is an auction-based advertising solution that enables brands to serve display creatives directly on retailer-owned placements such as search and category pages. The product is designed with an automation-first approach, allowing campaigns to launch with minimal configuration while supporting advanced optimization strategies such as dynamic targeting and automated bidding.

Prerequisites

Valid accountId
Proper authentication using a Bearer token
Access to the account and associated balances

Key Concepts

A campaign groups one or more Auction Display Line Items
Campaigns define attribution and frequency rules
Line items control delivery, bidding, and targeting

📘
Important
The buyType field is required at creation and cannot be modified after the campaign is created.

Endpoints Overview

Verb	Endpoint	Description
POST	`/accounts/{accountId}/display-campaigns`	Create a new Display Campaign
PATCH	`/display-campaigns/{displayCampaignId}`	Update an existing Display Campaign
POST	`/accounts/{accountId}/display-campaigns/search`	Search and filter Display Campaigns

Attributes

Attribute	Data Type	Description
`id` / `displayCampaignId`	string	Campaign ID generated by the system. Accepted values: int64 string. Writeable: No. Nullable: No
`name`*	string	Display name of the campaign. Writeable: Yes. Nullable: No
`buyType`*	string	Determines purchase type. Accepted values: `auction`, `preferred`. Writeable: No. Nullable: No
`companyName`	string	Name of the company running the campaign. Supply only. Writeable: Yes. Nullable: Yes
`onBehalfCompanyName`	string	Name of the company on whose behalf the campaign runs. Supply only. Writeable: Yes. Nullable: Yes
`frequencyCapping.cappingCount`	integer	Maximum number of impressions per user. Writeable: Yes. Nullable: Yes
`frequencyCapping.cappingDurationType`	string	Time window for capping. Accepted values: `session`, `day`. Writeable: Yes. Nullable: Yes
`attribution.clickAttributionWindow`	string	Click attribution window. Accepted values: `7d`, `14d`, `30d`. Writeable: Yes. Nullable: Yes
`attribution.clickAttributionScope`	string	Click attribution scope. Accepted values: `sameSku`, `sameSkuCategory`, `sameSkuCategoryBrand`. Writeable: Yes. Nullable: Yes
`attribution.viewAttributionWindow`	string	View attribution window. Accepted values: `7d`, `14d`, `30d`. Writeable: Yes. Nullable: Yes
`attribution.viewAttributionScope`	string	View attribution scope. Accepted values: `sameSku`, `sameSkuCategory`, `sameSkuCategoryBrand`. Writeable: Yes. Nullable: Yes
`drawableBalanceIds`	array[string]	Balance IDs used for spend. Writeable: No. Nullable: Yes

*Required at create operation

📘
Field Definitions

Writeable (Y/N): Indicates if the field can be modified in requests.

Nullable (Y/N): Indicates if the field can accept null/empty values.

Primary Key: A unique, immutable identifier of the entity, generated internally by Criteo. Primary keys are typically ID fields (e.g., retailerId, campaignId, lineItemId) and are usually required in the URL path.

Create Display Campaign

Creates a new Onsite Display campaign

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/display-campaigns

Sample Request

{
  "data": {
    "type": "DisplayCampaignCreateModel",
    "attributes": {
      "buyType": "auction",
      "name": "My Display Campaign",
      "companyName": "Acme Corp",
      "onBehalfCompanyName": "Acme Corp",
      "frequencyCapping": {
        "cappingCount": 5,
        "cappingDurationType": "day"
      },
      "attribution": {
        "clickAttributionWindow": "7d",
        "clickAttributionScope": "sameSkuCategory",
        "viewAttributionWindow": "7d",
        "viewAttributionScope": "sameSkuCategory"
      },
      "drawableBalanceIds": ["826490134880190464"]
    }
  }
}

Sample Response

{
  "data": {
    "id": "827998371331510272",
    "type": "DisplayCampaign",
    "attributes": {
      "buyType": "auction",
      "accountId": "697505769971195904",
      "status": "paused",
      "frequencyCapping": {
        "cappingCount": 5,
        "cappingDurationType": "session"
      },
      "attribution": {
        "clickAttributionWindow": "7d",
        "clickAttributionScope": "sameSkuCategory",
        "viewAttributionWindow": "7d",
        "viewAttributionScope": "sameSkuCategory"
      },
      "drawableBalanceIds": [],
      "name": "f06addfb-d7c9-4483-9b71-fcb4766eb78a",
      "companyName": null,
      "onBehalfCompanyName": null
    }
  },
  "warnings": [],
  "errors": []
}

Update Display Campaign

Updates an existing campaign using a partial update.

https://api.criteo.com/{version}/retail-media/display-campaigns/{displayCampaignId}

📘
Important
Only the fields included in the request are updated. Unincluded fields remain unchanged. buyType cannot be modified after creation.

Sample Request

{
  "data": {
    "type": "DisplayCampaignPatchModel",
    "attributes": {
      "frequencyCapping": {
        "value": {
          "cappingCount": 5,
          "cappingDurationType": "session"
        }
      },
      "attribution": {
        "clickAttributionWindow": "7d",
        "clickAttributionScope": "sameSkuCategory",
        "viewAttributionWindow": "7d",
        "viewAttributionScope": "sameSkuCategory"
      },
      "name": "f3949adc-1549-4ab3-bea4-e54b38f93142"
    }
  }
}

Search Display Campaigns

Searches campaigns using filters. This endpoint supports pagination using offset and limit.

https://api.criteo.com/{version}/retail-media/accounts/{accountId}/display-campaigns/search?offset=0&limit=100

Sample Request

{
  "data": {
    "type": "DisplayCampaignSearchModel",
    "attributes": {
      "campaignIds": [],
      "buyType": "auction"
    }
  }
}

Responses

Response	Title	Detail	Troubleshooting
🟢 `200`	Success	Request processed successfully	Verify response payload
🟢 `201`	Created	Campaign successfully created	N/A
🔴 `400`	Invalid Request	Missing or invalid fields	Check required fields like `buyType`
🔴 `401`	Unauthorized	Invalid or missing token	Verify Bearer token
🔴 `403`	Forbidden	Access denied	Check account permissions