> ## 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.

# Onsite Display Campaigns

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 <div className="relative mt-7">
      <span className={`absolute -top-2 -left-2 z-10 ${styles.bg} text-white px-2.5 py-0.5 rounded-full text-xs font-bold tracking-wide`}>
        {key}
      </span>
      {children}
    </div>;
};

## **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

<Info>
  **Important**

  The `buyType` field is required at creation and cannot be modified after the campaign is created.
</Info>

***

## Endpoints Overview

<table>
  <thead>
    <tr>
      <th>
        <p>
          Verb
        </p>
      </th>

      <th>
        <p>
          Endpoint
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/display-campaigns
          </code>
        </p>
      </td>

      <td>
        <p>
          Create a new Display Campaign
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            PATCH
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /display-campaigns/\{displayCampaignId}
          </code>
        </p>
      </td>

      <td>
        <p>
          Update an existing Display Campaign
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <b>
            POST
          </b>
        </p>
      </td>

      <td>
        <p>
          <code>
            /accounts/\{accountId}/display-campaigns/search
          </code>
        </p>
      </td>

      <td>
        <p>
          Search and filter Display Campaigns
        </p>
      </td>
    </tr>
  </tbody>
</table>

***

## Attributes

<table>
  <thead>
    <tr>
      <th>
        <p>
          Attribute
        </p>
      </th>

      <th>
        <p>
          Data Type
        </p>
      </th>

      <th>
        <p>
          Description
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          <code>
            id
          </code>

          /

          <code>
            displayCampaignId
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Campaign ID generated by the system. Accepted values: int64 string. Writeable: No. Nullable: No
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            name
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Display name of the campaign. Writeable: Yes. Nullable: No
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            buyType
          </code>

          <span>\*</span>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Determines purchase type. Accepted values:

          <code>
            auction
          </code>

          ,

          <code>
            preferred
          </code>

          . Writeable: No. Nullable: No
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            companyName
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Name of the company running the campaign. Supply only. Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            onBehalfCompanyName
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Name of the company on whose behalf the campaign runs. Supply only. Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            frequencyCapping.cappingCount
          </code>
        </p>
      </td>

      <td>
        <p>
          integer
        </p>
      </td>

      <td>
        <p>
          Maximum number of impressions per user. Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            frequencyCapping.cappingDurationType
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Time window for capping. Accepted values:

          <code>
            session
          </code>

          ,

          <code>
            day
          </code>

          . Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            attribution.clickAttributionWindow
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Click attribution window. Accepted values:

          <code>
            7d
          </code>

          ,

          <code>
            14d
          </code>

          ,

          <code>
            30d
          </code>

          . Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            attribution.clickAttributionScope
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          Click attribution scope. Accepted values:

          <code>
            sameSku
          </code>

          ,

          <code>
            sameSkuCategory
          </code>

          ,

          <code>
            sameSkuCategoryBrand
          </code>

          . Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            attribution.viewAttributionWindow
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          View attribution window. Accepted values:

          <code>
            7d
          </code>

          ,

          <code>
            14d
          </code>

          ,

          <code>
            30d
          </code>

          . Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            attribution.viewAttributionScope
          </code>
        </p>
      </td>

      <td>
        <p>
          string
        </p>
      </td>

      <td>
        <p>
          View attribution scope. Accepted values:

          <code>
            sameSku
          </code>

          ,

          <code>
            sameSkuCategory
          </code>

          ,

          <code>
            sameSkuCategoryBrand
          </code>

          . Writeable: Yes. Nullable: Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            drawableBalanceIds
          </code>
        </p>
      </td>

      <td>
        <p>
          array\[string]
        </p>
      </td>

      <td>
        <p>
          Balance IDs used for spend. Writeable: No. Nullable: Yes
        </p>
      </td>
    </tr>
  </tbody>
</table>

*\*Required at create operation*

<Info>
  **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.
</Info>

***

## Create Display Campaign

Creates a new Onsite Display campaign

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/display-campaigns
  ```
</EndpointBadge>

**Sample Request**

```json theme={null}
{
  "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**

```json theme={null}
{
  "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.

<EndpointBadge method="patch">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/display-campaigns/{displayCampaignId}
  ```
</EndpointBadge>

<Info>
  **Important**

  Only the fields included in the request are updated. Unincluded fields remain unchanged. `buyType` cannot be modified after creation.
</Info>

**Sample Request**

```json theme={null}
{
  "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`.

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/{version}/retail-media/accounts/{accountId}/display-campaigns/search
  ```
</EndpointBadge>

**Sample Request**

```json theme={null}
{
  "data": {
    "type": "DisplayCampaignSearchModel",
    "attributes": {
      "campaignIds": [],
      "buyType": "auction"
    }
  }
}
```

***

## Responses

<table>
  <thead>
    <tr>
      <th>
        <p>
          Response
        </p>
      </th>

      <th>
        <p>
          Title
        </p>
      </th>

      <th>
        <p>
          Detail
        </p>
      </th>

      <th>
        <p>
          Troubleshooting
        </p>
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        <p>
          🟢

          <code>
            200
          </code>
        </p>
      </td>

      <td>
        <p>
          Success
        </p>
      </td>

      <td>
        <p>
          Request processed successfully
        </p>
      </td>

      <td>
        <p>
          Verify response payload
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🟢

          <code>
            201
          </code>
        </p>
      </td>

      <td>
        <p>
          Created
        </p>
      </td>

      <td>
        <p>
          Campaign successfully created
        </p>
      </td>

      <td>
        <p>
          N/A
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            400
          </code>
        </p>
      </td>

      <td>
        <p>
          Invalid Request
        </p>
      </td>

      <td>
        <p>
          Missing or invalid fields
        </p>
      </td>

      <td>
        <p>
          Check required fields like

          <code>
            buyType
          </code>
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            401
          </code>
        </p>
      </td>

      <td>
        <p>
          Unauthorized
        </p>
      </td>

      <td>
        <p>
          Invalid or missing token
        </p>
      </td>

      <td>
        <p>
          Verify Bearer token
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          🔴

          <code>
            403
          </code>
        </p>
      </td>

      <td>
        <p>
          Forbidden
        </p>
      </td>

      <td>
        <p>
          Access denied
        </p>
      </td>

      <td>
        <p>
          Check account permissions
        </p>
      </td>
    </tr>
  </tbody>
</table>