Skip to main content

​
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
ImportantThe 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 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.
ImportantOnly 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. 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 likebuyType

🔴401

Unauthorized

Invalid or missing token

Verify Bearer token

🔴403

Forbidden

Access denied

Check account permissions