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

# Preferred Deals Line Items

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>;
};

<Info>
  A new unified [Line Item Core](/retail-media/experimental/docs/line-items-core) endpoint is replacing the type-specific creation routes. This page remains available in the meantime.
</Info>

* A *line item* holds *promoted products* to advertise on any single retailer
* Line items have bid settings, start & end dates, and optional budgeting & pacing controls
* Budgets may additionally be controlled at the campaign level
* Several [reports](/retail-media/v2025.07/docs/demand-side-analytics-get-started) are available to measure line item performance
* Campaigns are limited to 10,000 non-archived line items
* Line items are archived automatically 90 days after its end date

## Endpoints

* `GET /campaigns/{campaignId}/preferred-line-items` Get all Preferred Deals Line items from a specific Campaign
* `POST /campaigns/{campaignId}/preferred-line-items` Creates a Preferred Deals Line item
* `GET /preferred-line-items/{lineItemId}` Get a specific Preferred Deals Line item
* `PUT /preferred-line-items/{lineItemId}` Updates a specific Preferred Deals Line item

<Info>
  - Create operations using the `POST` method expect every **Required (R)** field; omitting **Optional (O)** fields will set those fields to **Default** values\* Update operations using the `PUT` method expect every **Write (W)** field; omitting these fields is equivalent to setting them to `null`, if possible
</Info>

## Line Item Attributes

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

      <th>
        <p>
          Description
        </p>
      </th>

      <th>
        <p>
          Values
        </p>
      </th>

      <th>
        <p>
          Required
        </p>
      </th>

      <th>
        <p>
          Default
        </p>
      </th>

      <th>
        <p>
          Write
        </p>
      </th>

      <th>
        <p>
          Nullable
        </p>
      </th>
    </tr>
  </thead>

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

          string
        </p>
      </td>

      <td>
        <p>
          Line item ID
        </p>
      </td>

      <td>
        <p>
          int64
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            campaignId
          </code>

          string
        </p>
      </td>

      <td>
        <p>
          Campaign ID
        </p>
      </td>

      <td>
        <p>
          int64
        </p>
      </td>

      <td>
        <p>
          Required
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

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

          string
        </p>
      </td>

      <td>
        <p>
          Line item name; must be unique within a

          <a href="/retail-media/experimental/docs/campaigns">
            campaign
          </a>
        </p>
      </td>

      <td>
        <p>
          255 char limit
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          Write
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            targetRetailerId
          </code>

          string
        </p>
      </td>

      <td>
        <p>
          ID of the

          <a href="/retail-media/experimental/docs/retailers">
            retailer
          </a>

          the line item serves on
        </p>
      </td>

      <td>
        <p>
          int64
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            startDate
          </code>

          date
        </p>
      </td>

      <td>
        <p>
          Line item start date in the

          <a href="/retail-media/experimental/docs/accounts">
            account
          </a>

          <code>
            timeZone
          </code>
        </p>
      </td>

      <td>
        <p>
          YYYY-MM-DD
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          W
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            endDate
          </code>

          date
        </p>
      </td>

      <td>
        <p>
          Line item end date in the

          <a href="/retail-media/experimental/docs/accounts">
            account
          </a>

          <code>
            timeZone
          </code>

          ; serves indefinitely if omitted or set to

          <code>
            null
          </code>
        </p>
      </td>

      <td>
        <p>
          YYYY-MM-DD
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td>
        <p>
          <code>
            null
          </code>
        </p>
      </td>

      <td>
        <p>
          W
        </p>
      </td>

      <td>
        <p>
          Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            budget
          </code>

          number
        </p>
      </td>

      <td>
        <p>
          Line item lifetime spend cap;
        </p>
      </td>

      <td>
        <p>
          at least 0
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td>
        <p>
          <code>
            null
          </code>
        </p>
      </td>

      <td>
        <p>
          W
        </p>
      </td>

      <td>
        <p>
          Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            budgetSpent
          </code>

          number
        </p>
      </td>

      <td>
        <p>
          Amount the line item has already spent
        </p>
      </td>

      <td>
        <p>
          at least 0
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          <code>
            0.0
          </code>
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            budgetRemaining
          </code>

          number
        </p>
      </td>

      <td>
        <p>
          Amount the line item has remaining until cap is hit;

          <code>
            null
          </code>

          if budget is uncapped
        </p>
      </td>

      <td>
        <p>
          between 0 and

          <code>
            budget
          </code>
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          <code>
            null
          </code>
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          Yes
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            pacing
          </code>

          enum
        </p>
      </td>

      <td>
        <p>
          Way the budget will be spent, between the following values:
        </p>

        <p>
          <code>
            accelerated
          </code>

          (Spend as fast as possible) or

          <code>
            standard
          </code>

          (Spend evenly)
        </p>
      </td>

      <td>
        <p>
          <code>
            accelerated
          </code>

          ,

          <code>
            standard
          </code>
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            capping
          </code>

          object
        </p>
      </td>

      <td>
        <p>
          Frequency capping object
        </p>
      </td>

      <td />

      <td>
        <p>
          O
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            capping:range
          </code>

          number
        </p>
      </td>

      <td>
        <p>
          Frequency capping number
        </p>
      </td>

      <td>
        <p>
          rangeline
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            capping:type
          </code>

          enum
        </p>
      </td>

      <td>
        <p>
          Frequency capping type
        </p>
      </td>

      <td>
        <p>
          <code>
            day
          </code>

          ,

          <code>
            session
          </code>
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page
          </code>

          object
        </p>
      </td>

      <td />

      <td />

      <td />

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page:pageType
          </code>

          enum
        </p>
      </td>

      <td>
        <p>
          Page type to serve on
        </p>
      </td>

      <td>
        <p>
          <code>
            search
          </code>

          ,

          <code>
            home
          </code>

          ,

          <code>
            checkout
          </code>

          ,

          <code>
            category
          </code>

          ,

          <code>
            productDetail
          </code>

          ,

          <code>
            confirmation
          </code>

          ,

          <code>
            merchandising
          </code>

          ,

          <code>
            deals
          </code>
        </p>
      </td>

      <td>
        <p>
          R
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page:categories
          </code>

          objects array
        </p>
      </td>

      <td>
        <p>
          Categories to serve on. Only applies to

          <code>
            category
          </code>

          ,

          <code>
            productDetail
          </code>

          and

          <code>
            merchandising
          </code>

          page types
        </p>
      </td>

      <td />

      <td>
        <p>
          O
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page:categories:categoryId:value
          </code>
        </p>
      </td>

      <td />

      <td />

      <td />

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page:categories:includeChildren:value
          </code>
        </p>
      </td>

      <td />

      <td />

      <td />

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            page:searchKeywords
          </code>

          string array
        </p>
      </td>

      <td>
        <p>
          Keywords to serve on. Only applies to

          <code>
            search
          </code>

          page type
        </p>
      </td>

      <td />

      <td>
        <p>
          O
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            creativeId
          </code>

          string
        </p>
      </td>

      <td>
        <p>
          Identifier of the creative to be served with this line item
        </p>
      </td>

      <td />

      <td>
        <p>
          R
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            status
          </code>

          enum
        </p>
      </td>

      <td>
        <p>
          Line item status; can only be updated by a user to

          <code>
            active
          </code>

          or

          <code>
            paused
          </code>

          ; all other values are applied automatically depending on flight dates, financials, or missing attributes required for line item to serve
        </p>
      </td>

      <td>
        <p>
          <code>
            active
          </code>

          ,

          <code>
            paused
          </code>

          ,

          <code>
            scheduled
          </code>

          ,

          <code>
            ended
          </code>

          ,

          <code>
            budgetHit
          </code>

          ,

          <code>
            noFunds
          </code>

          ,

          <code>
            draft
          </code>

          ,

          <code>
            archived
          </code>
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td />

      <td />

      <td />
    </tr>

    <tr>
      <td>
        <p>
          <code>
            createdAt
          </code>

          timestamp
        </p>
      </td>

      <td>
        <p>
          Timestamp in UTC of line item creation
        </p>
      </td>

      <td>
        <p>
          ISO-8601
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>

    <tr>
      <td>
        <p>
          <code>
            updatedAt
          </code>

          timestamp
        </p>
      </td>

      <td>
        <p>
          Timestamp in UTC of last line item update
        </p>
      </td>

      <td>
        <p>
          ISO-8601
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>

      <td>
        <p>
          *
        </p>
      </td>
    </tr>
  </tbody>
</table>

## Create a Preferred Deals Line Item

This endpoint creates a new preferred deals line item in the specified campaign

<EndpointBadge method="post">
  ```http theme={null}
  https://api.criteo.com/experimental/retail-media/campaigns/{campaignId}/preferred-line-items
  ```
</EndpointBadge>

**Sample Request**

```bash expandable theme={null}
curl -L -X POST 'https://api.criteo.com/experimental/retail-media/campaigns/329628911113846784/preferred-line-items' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkZMNllURk1pcVliT1RGUW4yUmh3cWFLTnhuaGV1MFBJTjFlZU9ydnBoSWMiLCJ0eXAiOiJKV1QifQ.eyJjbGllbnRfaWQiOiJiZTYyYWJmYmNhYWI0NzdhOWQwYzYyNTMzNGEzMGIwNiIsInR5cGUiOiJhY2Nlc3NfdG9rZW4iLCJpYXQiOjE2NTY1MzYxMzksImV4cCI6MTY1NjUzNzA5OSwiaXNzIjoicHJpdmF0ZS1jcml0ZW8tZXhhbW9hdXRoIiwiYXVkIjoicHJpdmF0ZS1jcml0ZW8tZXhhbW9hdXRoIn0.FmNUnRDfkT3KZAnGCwzmbtnXEXvUB5VpsZ7-f2QgW94AJrLziFKYwBpHckxiH4Dg0BcM0o5UFbeB5qIkdBl8NFvgWYnMpnaZLj7z32U-jk7Cwm2kMVH4DwqONd_qRsSPhn4MGKgK74qXY4L1shAKKchIVQQ-j5tBmiIvbQxJriALdCPm61ZHtSXJkPWAt8eBSGjPrfXFdOlb4auVzuHb57mr-YHIJBgm7LiVb-43mKVZtSf9sIiJafCwV2iCnqD8WlVzuwrcP7HZsnYgiIjQg3-E00vE8BptesIKpJyTf-xIzQ52KyzVeIGrx4EU9F5dBPug49J0H3HgGqrVyzEXxg' \
--data-raw '{
    "data": {
        "type": "RetailMediaPDCampaignCreation",
        "attributes": {
            "name": "API PD Campaign V4 - categories",
            "startDate": "2022-06-29",
            "endDate": "2022-06-30",
            "pacing": "standard",
            "page": {
                "pageType": "category",
                "categories": [
                    {
                        "categoryID": "3595128",
                         "includeChildren": "false"
                    }
                ]
            },
            "targetRetailerId": "299",
            "budget": "1.00",
            "status": "draft",
            "capping": {
                "type": "day",
                "count": "5"
            },
            "creativeId": "231059293677002752"
        }
    }
}'
```

**Sample Response**

```json expandable theme={null}
{
    "data": {
        "attributes": {
            "name": "API PD Campaign V4 - categories",
            "startDate": "2022-06-29",
            "endDate": "2022-06-30",
            "status": "draft",
            "pacing": "standard",
            "capping": {
                "type": "day",
                "count": 5
            },
            "page": {
                "pageType": "category",
                "categories": [
                    {
                        "categoryId": "3595128",
                        "includeChildren": false
                    }
                ],
                "searchKeywords": null
            },
            "targetRetailerId": "299",
            "budget": 1.00000000,
            "campaignId": "329628911113846784",
            "budgetSpent": 0.00000000,
            "budgetRemaining": 1.00000000,
            "createdAt": "2022-06-29T21:01:04+00:00",
            "updatedAt": "2022-06-29T21:01:06+00:00",
            "creativeId": "231059293677002752",
            "id": "330090318158475264"
        },
        "id": "330090318158475264",
        "type": "RetailMediaPreferredLineItem"
    },
    "warnings": [],
    "errors": []
}
```

## Get All Preferred Deals Line Items

This endpoint lists all preferred deals line items in the specified campaign.  Results are paginated.

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/experimental/retail-media/campaigns/{campaignId}/preferred-line-items
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -X GET "https://api.criteo.com/experimental/retail-media/campaigns/8343086999167541140/preferred-line-items" \
    -H "Authorization: Bearer myaccesstoken"
```

**Sample Response**

```json expandable theme={null}
{
    "data": [
        {
            "type": "RetailMediaLineItem",
            "id": "9979917896105882144",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "My New Line Item 3",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2021-07-10",
                "endDate": "2021-07-14",
                "budget": 1520.00,
                "budgetSpent": 20.00,
                "budgetRemaining": 1500.00,
                "pacing": "accelerated",
                "capping": {
                    "type": "day",
                    "count": 5
                },
                "page": {
                    "pageType": "home",
                    "categories": null,
                    "searchKeywords": null
                },
                "status": "draft",
                "createdAt": "2020-04-04T06:11:23+00:00",
                "updatedAt": "2020-04-05T06:11:23+00:00",
                "creativeId": "231059024123875072"
            }
        },
 
        // ...
 
        {
            "type": "RetailMediaLineItem",
            "id": "6854840188706902009",
            "attributes": {
                "campaignId": "8343086999167541140",
                "name": "My New Line Item",
                "targetRetailerId": "18159942378514859684",
                "startDate": "2021-07-20",
                "endDate": "2021-07-21",
                "budget": 10.00,
                "budgetSpent": null,
                "budgetRemaining": null,
                "pacing": "standard",
                "capping": {
                    "type": "day",
                    "count": 5
                },
                "page": {
                    "pageType": "home",
                    "categories": null,
                    "searchKeywords": null
                },
                "status": "draft",
                "createdAt": "2020-04-06T06:11:23+00:00",
                "updatedAt": "2020-04-06T06:11:23+00:00",
                "creativeId": "231059024123875072"      
            }
        }
    ],
    "metadata": {
        "totalItemsAcrossAllPages": 105,
        "currentPageSize": 25,
        "currentPageIndex": 0,
        "totalPages": 5,
        "nextPage": "https://api.criteo.com/experimental/retail-media/campaigns/8343086999167541140/preferred-line-items?pageIndex=1&pageSize=25",
        "previousPage": null
    }
}
```

# Get a Specific Preferred Deals Line Item

This endpoint retrieves the specified preferred deals line item.

<EndpointBadge method="get">
  ```http theme={null}
  https://api.criteo.com/experimental/retail-media/preferred-line-items/{lineItemId}
  ```
</EndpointBadge>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.criteo.com/experimental/retail-media/preferred-line-items/2465695028166499188" \
      -H "Authorization: Bearer myaccesstoken"
  ```

  ```json JSON theme={null}
  {
      "data": { 
          "type": "RetailMediaLineItem",
          "id": "2465695028166499188",
          "attributes": {
              "campaignId": "8343086999167541140",
              "name": "My New Line Item",
              "targetRetailerId": "18159942378514859684",
              "startDate": "2021-07-20",
              "endDate": "2021-07-21",
              "budget": 10.00,
              "budgetSpent": null,
              "budgetRemaining": null,
              "pacing": "standard",
              "page": {
                  "pageType": "home",
                  "categories": null,
                  "searchKeywords": null
              },
              "capping": {
                  "type": "day",
                  "count": 5
              },
              "status": "draft",
              "createdAt": "2020-04-06T06:11:23+00:00",
              "updatedAt": "2020-04-06T06:11:23+00:00",
              "creativeId": "231059024123875072"
          }
      }
  }
  ```
</CodeGroup>

# Update a Specific Preferred Deals Line Item

This endpoint updates the specified preferred deals line item.  In this example, we update the pacing status from `accelerated` to `standard`. Also note the draft state of the line item because products to be promoted have not yet been added.

<EndpointBadge method="put">
  ```http theme={null}
  https://api.criteo.com/experimental/retail-media/preferred-line-items/{lineItemId}
  ```
</EndpointBadge>

**Sample Request**

```bash theme={null}
curl -X PUT "https://api.criteo.com/experimental/retail-media/preferred-line-items/2465695028166499188" \
    -H "Authorization: Bearer myaccesstoken" \
    -H "Content-Type: application/json" \
    -d '{
            "data": {
                "type": "RetailMediaLineItem",
                "id": "2465695028166499188",
                "attributes": {
                    "name": "My New Line Item",
                    "targetRetailerId": "18159942378514859684",
                    "startDate": "2021-07-20",
                    "endDate": "2021-07-21",
                    "budget": 10.00,
                    "pacing": "standard",
                    "page": {
                        "pageType": "home",
                        "categories": null,
                        "searchKeywords": null
                    },
                    "capping": {
                         "type": "day",
                         "count": 5
                    },
                    "status": "paused",
                    "creativeId": "231059024123875072"
                }
            }
        }'
```

**Sample Response**

```json theme={null}
{
    "data": { 
        "type": "RetailMediaLineItem",
        "id": "2465695028166499188",
        "attributes": {
            "name": "My New Line Item",
            "targetRetailerId": "18159942378514859684",
            "startDate": "2021-07-20",
            "endDate": "2021-07-21",
            "budget": 10.00,
            "budgetSpent": null,
            "budgetRemaining": null,
            "page": {
                "pageType": "home",
                "categories": null,
                "searchKeywords": null
            },
            "pacing": "standard",
            "capping": {
                "type": "day",
                "count": 5
            },
            "status": "draft",
            "createdAt": "2020-04-06T06:11:23+00:00",
            "updatedAt": "2020-04-06T06:17:48+00:00",
            "creativeId": "231059024123875072"
        }
    }
}
```