> ## 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.
# Line Item Core
> Create and manage the line items that control how a campaign delivers ads.
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 line item is a unit within a campaign that controls how ads are delivered. It identifies the retailer where ads can run, defines the active flight dates, and holds delivery settings for its campaign type. A campaign can contain multiple line items.
The line item core endpoints are shared across campaign types. They expose common fields through one contract instead of separate Sponsored Products and Onsite Display routes.
The referenced `campaignId` determines the line-item type. Type-specific fields are carried in a matching details object alongside the common attributes. Include only the details object supported by the campaign type.
The long-term goal is to support line-item core operations across campaign types. Initial documented support targets Onsite Display Auction campaigns and uses `onsiteDisplayDetails`. Additional details objects will be documented as support is added.
This endpoint replaces the following type-specific creation routes, which remain available in the meantime:
* [Onsite Display Line Items](/retail-media/experimental/docs/onsite-display-line-items)
* [Onsite Sponsored Products Line Items](/retail-media/experimental/docs/onsite-sponsored-products-line-items)
* [Preferred Deals Line Items](/retail-media/experimental/docs/preferred-deals-line-items)
## Endpoints
| Method | Endpoint | Description |
| ------- | ---------------------------- | ------------------------------- |
| `POST` | `/line-items` | Create a line-item core entity. |
| `PATCH` | `/line-items/{line-item-id}` | Update an existing line item. |
## Create a Line Item Core
Creates a line-item core entity under an existing campaign.
```http theme={null}
https://api.criteo.com/experimental/retail-media/line-items
```
### Request Attributes
| Attribute | Required | Description |
| ---------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | Yes | Display name of the line item. It must be unique within the campaign and contain 2–255 characters after trimming. |
| `retailerId` | Yes | External ID of the retailer associated with the line item. If the campaign specifies a retailer, the line-item retailer must match it. |
| `campaignId` | Yes | External ID of the existing campaign that owns the line item and determines which type-specific details object is accepted. |
| `flightDates` | Yes | Active date range. `startDate` is required and must precede `endDate`; whether `endDate` is required depends on the campaign and buy type. |
| `isPaused` | No | Whether the line item is paused. Defaults to `false`. |
| `serveToOptOutUser` | No | Whether ads can serve to users who opted out of personalization. |
| `onsiteDisplayDetails.auctionDetails.isDynamicMatch` | No | Initial Onsite Display Auction-specific setting. Determines whether to replace manual SKU curation by serving only products relevant to the page context. |
The resource `type` is `line-item`. Do not send response-only fields such as `lineItemId`, `type`, `financialStatus`, `effectiveFlightDates`, or `conquestingSettings` inside `attributes`.
**Sample Request**
```json theme={null}
{
"data": {
"type": "line-item",
"attributes": {
"name": "Back-to-school display",
"isPaused": false,
"retailerId": "12345",
"campaignId": "987654321",
"flightDates": {
"startDate": "2026-09-01T00:00:00Z",
"endDate": "2026-09-30T23:59:59Z"
},
"serveToOptOutUser": false,
"onsiteDisplayDetails": {
"auctionDetails": {
"isDynamicMatch": true
}
}
}
}
}
```
**Sample Response**
```json theme={null}
{
"data": {
"id": "112233445566778899",
"type": "line-item",
"attributes": {
"lineItemId": "112233445566778899",
"type": "OnsiteDisplay",
"name": "Back-to-school display",
"isPaused": false,
"financialStatus": "Active",
"retailerId": "12345",
"campaignId": "987654321",
"effectiveFlightDates": {
"startDate": "2026-09-01T00:00:00Z",
"endDate": "2026-09-30T23:59:59Z"
},
"serveToOptOutUser": false,
"conquestingSettings": {
"conquestingAdStrategyEnabled": false,
"neutralAdStrategyEnabled": true,
"defensiveAdStrategyEnabled": true,
"isAdStrategyLocked": false
},
"onsiteDisplayDetails": {
"auctionDetails": {
"isDynamicMatch": true
}
}
}
}
}
```
### Errors
| HTTP status | Code | Description |
| ----------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| `400` | `invalid-line-item-attributes` | The type-specific attributes do not match the campaign or buy type, or auction attributes were supplied for a non-auction campaign. |
| `400` | `invalid-name` | The name is blank or outside the supported length. |
| `400` | `invalid-flight-dates` | The flight dates are missing or invalid. |
| `400` | `invalid-retailer-id` | The retailer ID is improperly formatted or, when the campaign specifies a retailer, does not match it. |
| `400` | `duplicate-name` | A line item with the same name already exists under the campaign. |
| `400` | `unsupported-campaign-type` | The campaign type is not supported by the current implementation. |
| `401` | `unauthorized` | The caller is not authenticated. |
| `403` | `forbidden` | The caller cannot create a line item for the target campaign and retailer. |
***
## Update a Line Item Core
Updates an existing line item. This is a partial update: only the fields included in the request body are changed. Omitted fields keep their current values.
`campaignId` and `retailerId` cannot be changed after creation.
```http theme={null}
https://api.criteo.com/experimental/retail-media/line-items/{line-item-id}
```
### Path Parameters
| Parameter | Description |
| -------------- | ------------------------------------------------- |
| `line-item-id` | The unique identifier of the line item to update. |
### Request Attributes
| Attribute | Description |
| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | New display name. Must be unique within the campaign and contain 2–255 characters after trimming. |
| `flightDates.startDate` | Updated start date for the line item's active period. |
| `flightDates.endDate` | Updated end date for the line item's active period. |
| `isPaused` | Set to `true` to pause the line item or `false` to unpause it. |
| `serveToOptOutUser` | Whether ads can serve to users who opted out of personalization. |
| `onsiteDisplayDetails.auctionDetails.isDynamicMatch` | Onsite Display Auction-specific. Determines whether to replace manual SKU curation by serving only products relevant to the page context. |
The resource `type` is `line-item`. Do not send response-only fields such as `lineItemId`, `type`, `financialStatus`, `effectiveFlightDates`, or `conquestingSettings` inside `attributes`.
**Sample Request**
```json theme={null}
{
"data": {
"type": "line-item",
"attributes": {
"name": "Back-to-school display — extended",
"flightDates": {
"endDate": "2026-10-15T23:59:59Z"
},
"isPaused": false
}
}
}
```
**Sample Response**
```json theme={null}
{
"data": {
"id": "112233445566778899",
"type": "line-item",
"attributes": {
"lineItemId": "112233445566778899",
"type": "OnsiteDisplay",
"name": "Back-to-school display — extended",
"isPaused": false,
"financialStatus": "Active",
"retailerId": "12345",
"campaignId": "987654321",
"effectiveFlightDates": {
"startDate": "2026-09-01T00:00:00Z",
"endDate": "2026-10-15T23:59:59Z"
},
"serveToOptOutUser": false,
"conquestingSettings": {
"conquestingAdStrategyEnabled": false,
"neutralAdStrategyEnabled": true,
"defensiveAdStrategyEnabled": true,
"isAdStrategyLocked": false
},
"onsiteDisplayDetails": {
"auctionDetails": {
"isDynamicMatch": true
}
}
}
}
}
```
### Errors
| HTTP Status | Code | Description |
| ----------- | ------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `400` | `invalid-name` | The name is blank or outside the supported length. |
| `400` | `invalid-flight-dates` | The flight dates are missing or invalid. |
| `400` | `duplicate-name` | A line item with the same name already exists under the campaign. |
| `400` | `invalid-line-item-attributes` | The type-specific attributes do not match the line item's campaign or buy type. |
| `400` | `invalid-dynamic-match` | `isDynamicMatch` cannot be changed once the line item is approved, or set to `false` once set to `true`. |
| `401` | `unauthorized` | The caller is not authenticated. |
| `403` | `forbidden` | The caller cannot update this line item. |