> ## 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, retrieve, 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 <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>;
};

## Overview

A line item is a unit within a campaign that controls how ads are delivered. It identifies the retailer where ads can run 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.

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

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 |
| - | - | - |
| `GET` | `/line-items/{lineItemId}` | Retrieve a consolidated view of a line item. |
| `POST` | `/line-items` | Create a line-item core entity. |
| `PATCH` | `/line-items/{lineItemId}` | Update an existing line item. |

## Get a Line Item

Retrieves a consolidated view of a line item: its core fields, targeting, ad content (products and creatives), and bidding settings.

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

### Path Parameters

| Parameter | Description |
| - | - |
| `line-item-id` | The unique identifier of the line item to retrieve. |

### Response Attributes

All attributes below are nested under `data.attributes`.

| Attribute | Type | Description |
| - | - | - |
| `core` | object | Core line item fields. Same shape as the `line-item` resource attributes returned by [Create](#create-a-line-item-core) and [Update](#update-a-line-item-core), always present when the request succeeds. |
| `targeting` | object or null | Targets configured for the line item. See [Targeting](/retail-media/experimental/docs/line-item-targets#target-attributes) for the `targets[]` field descriptions. |
| `adContent` | object or null | Ad content associated with the line item. Null only when both `products` and `creatives` are unavailable. |
| `adContent.products` | object or null | Products in the line item's product pool. Same shape as the resource described in [Line Item Products](/retail-media/experimental/docs/line-item-products#request-attributes), with `approvalStatus` populated on each product. |
| `adContent.creatives` | object or null | Creatives associated with the line item. |
| `adContent.creatives.mediaType` | string or null | `Display` or `Video`. Null when not yet known. |
| `adContent.creatives.creatives` | array | The line item's associated creatives. Empty when none are associated. |
| `adContent.creatives.creatives[].creative.id` | string | ID of the creative. |
| `adContent.creatives.creatives[].creative.modifiedAt` | string | When the creative revision currently associated with the line item was associated. |
| `adContent.creatives.creatives[].approvalStatus` | string | Approval status of the creative associated to the line item. |
| `adContent.creatives.creatives[].creativePreviewCode` | string or null | The Creative Live Demo preview code. Null if the retailer does not support this feature. |
| `adContent.creatives.creatives[].creativeProductCollections` | array | The ordered product collections of the associated creative. See [Fetch Line Item Creatives](/retail-media/experimental/docs/line-item-creatives#fetch-line-item-creatives) for the collection and product field descriptions. |
| `bidding` | object or null | Bidding settings for the line item. See [Bid Strategy Settings](/retail-media/experimental/docs/bidding-strategy-settings#response-attributes) for the `cpm` field descriptions. |

**Sample Request**

```bash theme={null}
curl -L -X GET \
  'https://api.criteo.com/experimental/retail-media/line-items/112233445566778899' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <MY_ACCESS_TOKEN>'
```

**Sample Response** — `200 OK`

```json theme={null}
{
  "data": {
    "id": "112233445566778899",
    "type": "LineItemDetails",
    "attributes": {
      "core": {
        "lineItemId": "112233445566778899",
        "type": "OnsiteDisplay",
        "name": "Back-to-school display",
        "isPaused": false,
        "budgetStatus": "BudgetAvailable",
        "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": {
          "frequencyCapping": {
            "cappingCount": 5,
            "cappingDurationType": "Day"
          },
          "auctionDetails": {
            "isDynamicMatch": true
          }
        }
      },
      "targeting": {
        "targets": [
          {
            "targetType": "Category",
            "negative": false,
            "bidMultiplier": 1.5,
            "approvalStatus": "Approved",
            "categoryTargetDetails": {
              "categoryId": "1001",
              "includeChildren": true
            }
          }
        ]
      },
      "adContent": {
        "products": {
          "productType": "DisplayProduct",
          "displayProductDetails": [
            {
              "productId": "sku-12345",
              "approvalStatus": "Approved"
            }
          ]
        },
        "creatives": {
          "mediaType": "Display",
          "creatives": [
            {
              "creative": {
                "id": "123",
                "modifiedAt": "2026-08-13T14:30:00Z"
              },
              "approvalStatus": "Approved",
              "creativePreviewCode": "preview-code",
              "creativeProductCollections": [
                {
                  "isMandatory": false,
                  "products": [
                    {
                      "id": "sku-12345",
                      "approvalStatus": "Approved"
                    }
                  ]
                }
              ]
            }
          ]
        }
      },
      "bidding": {
        "cpm": {
          "bidStrategy": "Adaptive",
          "standardBiddingSettings": {
            "auctionBids": [
              {
                "pageType": "Search",
                "bid": 1.25
              }
            ]
          },
          "adaptiveBiddingSettings": {
            "maxBid": 3.5
          }
        }
      }
    }
  },
  "warnings": []
}
```

### Partial Availability

`core` is always required: if it cannot be retrieved, the endpoint returns a non-`200` response with no `data`, forwarding the downstream error and status code unchanged.

`targeting`, `adContent.products`, `adContent.creatives`, and `bidding` are independently optional:

* If one of these is temporarily unavailable (for example, a downstream dependency failure), the response still returns `200 OK` with that attribute set to `null` and a warning appended to the top-level `warnings` array.
* `adContent` itself is `null` only when both `products` and `creatives` are unavailable; if either succeeds, `adContent` is present with the other field set to `null`.
* If a scope does not apply to the line item's type (for example, requesting creatives for a line item type that does not support them), the attribute is `null` **without** a warning, since the scope does not apply rather than being unavailable.

| Warning Code | `instance` | Meaning |
| - | - | - |
| `line-item-targeting-unavailable` | `@data/attributes/targeting` | Targeting could not be retrieved. |
| `line-item-ad-content-products-unavailable` | `@data/attributes/adContent/products` | Products could not be retrieved. |
| `line-item-ad-content-creatives-unavailable` | `@data/attributes/adContent/creatives` | Creatives could not be retrieved. |
| `line-item-bidding-unavailable` | `@data/attributes/bidding` | Bidding settings could not be retrieved. |

Clients should always inspect the `warnings` array, even on a `200 OK` response, since it can indicate that part of the consolidated view is incomplete.

### Errors

| HTTP status | Description |
| - | - |
| `401` | The caller is not authenticated. |
| `403` | The line item does not exist, or the caller cannot access it. |
| `5xx` | The core line item could not be retrieved; the error and status code are forwarded from the underlying service unchanged. |

***

## Create a Line Item Core

Creates a line-item core entity under an existing campaign.

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

### 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. |
| `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.frequencyCapping` | No | Limits how often one user may be shown this Onsite Display line item's ads. Omit it to leave the line item uncapped. |
| `onsiteDisplayDetails.frequencyCapping.cappingCount` | Required when `frequencyCapping` is supplied | Maximum number of times the ads may be shown within the selected duration. Must be from `1` to `20`. |
| `onsiteDisplayDetails.frequencyCapping.cappingDurationType` | Required when `frequencyCapping` is supplied | Period the count applies to: `Session` or `Day`. |
| `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`, `budgetStatus`, `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",
      "serveToOptOutUser": false,
      "onsiteDisplayDetails": {
        "frequencyCapping": {
          "cappingCount": 5,
          "cappingDurationType": "Day"
        },
        "auctionDetails": {
          "isDynamicMatch": true
        }
      }
    }
  }
}
```

### Response Attributes

All attributes below are nested under `data.attributes`. Alongside the attributes accepted on creation, the response carries read-only fields such as the following enum fields.

| Attribute | Type | Description |
| - | - | - |
| `type` | string | Type of line item: `SponsoredProduct` or `OnsiteDisplay`. |
| `budgetStatus` | string | Whether the line item has budget headroom to serve ads: `BudgetAvailable`, `DailyBudgetReached`, `MonthlyBudgetReached`, `TotalBudgetReached` or `Unknown`. `Unknown` means the status could not be determined. |

**Sample Response**

```json theme={null}
{
  "data": {
    "id": "112233445566778899",
    "type": "line-item",
    "attributes": {
      "lineItemId": "112233445566778899",
      "type": "OnsiteDisplay",
      "name": "Back-to-school display",
      "isPaused": false,
      "budgetStatus": "BudgetAvailable",
      "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": {
        "frequencyCapping": {
          "cappingCount": 5,
          "cappingDurationType": "Day"
        },
        "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-campaign-schedule` | The campaign has no schedule from which the API can derive the line item's flight dates. |
| `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` | `invalid-frequency-capping` | The duration is not `Session` or `Day`, the count is outside `1`–`20`, or the parent campaign already has frequency capping. |
| `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.

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

### 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. |
| `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.frequencyCapping` | Frequency-cap setting for an Onsite Display line item. Omit it to leave the cap unchanged; send `{ "value": null }` to remove the cap. |
| `onsiteDisplayDetails.frequencyCapping.value.cappingCount` | Maximum number of times the ads may be shown within the selected duration. Must be from `1` to `20`; required when setting a cap. |
| `onsiteDisplayDetails.frequencyCapping.value.cappingDurationType` | Period the count applies to: `Session` or `Day`. Required when setting a cap. |
| `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`, `budgetStatus`, `effectiveFlightDates`, or `conquestingSettings` inside `attributes`.

**Sample Request**

```json theme={null}
{
  "data": {
    "type": "line-item",
    "attributes": {
      "name": "Back-to-school display — extended",
      "isPaused": false,
      "onsiteDisplayDetails": {
        "frequencyCapping": {
          "value": {
            "cappingCount": 5,
            "cappingDurationType": "Session"
          }
        }
      }
    }
  }
}
```

The response attributes are the same as for [Create](#create-a-line-item-core).

**Sample Response**

```json theme={null}
{
  "data": {
    "id": "112233445566778899",
    "type": "line-item",
    "attributes": {
      "lineItemId": "112233445566778899",
      "type": "OnsiteDisplay",
      "name": "Back-to-school display — extended",
      "isPaused": false,
      "budgetStatus": "BudgetAvailable",
      "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": {
        "frequencyCapping": {
          "cappingCount": 5,
          "cappingDurationType": "Session"
        },
        "auctionDetails": {
          "isDynamicMatch": true
        }
      }
    }
  }
}
```

### Errors

| HTTP Status | Code | Description |
| - | - | - |
| `400` | `invalid-name` | The name is blank or outside the supported length. |
| `400` | `duplicate-name` | A line item with the same name already exists under the campaign. |
| `400` | `invalid-frequency-capping` | The duration is not `Session` or `Day`, the count is outside `1`–`20`, or the parent campaign already has frequency capping. |
| `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. |