## Endpoints | Method | Endpoint | Description | | --- | --- | --- | | **GET** | `/campaigns/{campaignId}/auction-line-items` | Get all auction line items from a specific campaign | | **POST** | `/campaigns/{campaignId}/auction-line-items` | Create a new auction line item | | **GET** | `/auction-line-items/{lineItemId}` | Get a specific auction line item | | **PUT** | `/auction-line-items/{lineItemId}` | Update a specific auction line item | **Field Definitions** - `Create` operations using the `POST` method expect every **Required** field; omitting **Optional** fields will set those fields to **Default** values. - `Update` operations using the `PUT` method expect every **Writeable** field; omitting these fields is equivalent to setting them to `null`, if possible. ## Line Item Attributes | Attribute | Data Type | Description | | --- | --- | --- | | `id` | string | Auction line item ID, generated internally by Criteo
Accepted values: string of int64
Writeable? N / Nullable? N | | `name`* | string | Line item name, must be unique within the [Campaign](https://developers.criteo.com/retail-media/docs/campaign)
Accepted values: between 2 and 255-chars string
Writeable? Y / Nullable? N | | `campaignId`* | string | Campaign ID, in which the respective line item belongs and generated internally by Criteo
Accepted values: string of int64
Writeable? N / Nullable? N | | `targetRetailerId`* | string | Retailer ID where the line item will serve ads on. For retailer-budgets campaigns, must match the campaign’s`retailerId`. Only one retailer is allowed per retailer-billed campaign.
Accepted values: string of int64
Writeable? N / Nullable? N | | `startDate`* | date | Start date of the line item, used to schedule its activation and start serving ads. To understand the conditions that will cause a status to change, check out Campaign & Line Item Status
ℹ️ This now supports datetime offset to define the desired time zone, in the format of`±hh:mm`. If omitted in create/update operations, UTC will be considered the default time zone. Values are returned in UTC in responses; dates are normalized to account timezone internally.
Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm or yyyy-mm-dd`(in ISO-8601)
Writeable? Y / Nullable? N | | `endDate` | date | End date of the line item; serves ads indefinitely if omitted or set to`null`. To understand the conditions that will cause a status to change, check out Campaign & Line Item Status
ℹ️ This now supports datetime offset to define the desired time zone, in the format of`±hh:mm`. If omitted in create/update operations, UTC will be considered the default time zone. Values are returned in UTC in responses; dates are normalized to account timezone internally.
Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm or yyyy-mm-dd`(in ISO-8601 )
Default: if`null`or absent, line item will serve ads indefinitely
Writeable? Y / Nullable? Y | | `budget` | decimal | Lifetime spend cap of line item (optional), uncapped if omitted or set to`null`
Accepted values:`budget`≥ 0.0
Default:`null`
Writeable? Y / Nullable? Y | | `budgetSpent` | decimal | Budget amount the line item has already spent
Accepted values:`budgetSpent`≥ 0.0
Default:`0.0`
Writeable? N / Nullable? N | | `budgetRemaining` | decimal | Amount the line item has remaining until cap is hit;`null`if budget is uncapped
Accepted values: 0 ≤`budgetRemaining`≤`budget`
Default:`0.0`
Writeable? N / Nullable? Y | | `monthlyPacing` | decimal | Amount the line item can spend per calendar month (optional), in the Account time zone. Omitting or setting to`null`leaves the monthly spend uncapped.
Accepted values:`monthlyPacing`≥ 0.0 (or`null`)
Default:`0.0`
Writeable? Y / Nullable? Y | | `dailyPacing` | decimal | Amount the line item can spend per calendar day (optional), in the Account time zone. It resets each day; overwritten by calculation if`isAutoDailyPacing`is enabled; uncapped if omitted or set to`null`
Accepted values:`dailyPacing`≥ 0.0 (or`null`)
Default:`0.0`
Writeable? Y / Nullable? Y | | `isAutoDailyPacing` | boolean | To activate, either line item`endDate`and budget, or`monthlyPace`, must be specified; overwrites`dailyPacing`with calculation if not set prior
Accepted values:`true`,`false`
Default:`false`
Writeable? Y / Nullable? N | | `bidStrategy` | enum | Indicate whether Adaptive CPC is enabled or not`automated`will trigger a validation against the`maxBid`to ensure that it is present.`manual`will trigger a validation against the`targetBid`to ensure that a bid for the line item have been input.
Accepted values:`automated`,`manual`
Default:`manual`
Writeable? Y / Nullable? N | | `optimizationStrategy` | enum | Bid algorithm optimizing for sales conversions, sales revenue or clicks
Accepted values:`conversion`,`revenue`,`clicks`
Default:`conversion`
Writeable? Y / Nullable? N | | `targetBid` | bidStrategy decimal | If optimizing for`conversion`or`revenue`, a target average amount to bid (as each bid is modulated up/down by our optimization algorithm); else bids stay constant, if optimizing for`clicks`Bidding is uncapped if omitted or set to`null`
ℹ️ Note:
- Must meet`minBid`for line item to deliver ads, which depends on selected products (available through the Catalog)
- Input excludes platform fees
Accepted values: at least the greatest value of`minBid`across all products in the line item
Default:`0.3`
Writeable? Y / Nullable? Y | | `maxBid` | decimal | If optimizing for`conversion`or`revenue`, the maximum amount allowed to bid for each display (respected regardless of`targetBid`). Does not apply if optimizing for`clicks`Bidding is uncapped if omitted or set to`null`
ℹ️ Note:
- Must meet`minBid`for line item to deliver ads, which depends on selected products (available through the Catalog)
- Input excludes platform fees
Accepted values: at least`0.1`
⚠️ **Note:** As of `2026-01`, `maxBid` is required when `bidStrategy: automated`. When set to `null`, the API returns `0` in responses, but the system treats it internally as uncapped (no bid ceiling).
Writeable? Y / Nullable? Y | | `status` | enum | Line item status; can only be updated by a user to`active`or`paused`; all other values are applied automatically depending on financials, flight dates, or missing attributes required for line item to serve. To understand the conditions that will cause a status to change, check out Campaign & Line Item Status
Accepted values:`active`,`paused`,`scheduled`,`ended`,`budgetHit`,`noFunds`,`draft`,`archived`
Writeable? Y / Nullable? N | | `flightSchedule` | object | Settings allowing custom scheduling for serving ads serving, organized by a combination of`legs`. In case of`null`or empty`legs`, the line item status will remain unchanged along the weekdays and hours, as long as other delivery parameters are respected - see Campaign & Line Item Status
Accepted values: see below
Writeable? Y / Nullable? Y | | `keywordStrategy` | enum | Keyword strategy used to target users according to the promoted products appended in the line item and their competitors
ℹ️ Note: “ _Conquesting_” is not available for all retailers; when creating a new line item for those retailers, a validation error will return which can be avoided by omitting this attribute from the request
Accepted values:
- `genericAndBranded`: enables users who submit general keywords and also keywords related to the brand(s) to target the promoted products associated with the line item (default behavior)
- `conquesting`: enables users who submit keywords identified as competitor(s) from the brand(s) related to the promoted products associated with the line item (manual review required)
- `genericBrandedAndConquesting`: enables users who submit keywords related to both brand(s) and competitor(s) from the promoted products of line item (manual review required)
Default:`genericAndBranded`
Writeable? Y / Nullable? N | | `createdAt` | timestamp | Timestamp of line item creation, in UTC
Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm`(in ISO-8601)
Writeable? N / Nullable? N | | `updatedAt` | timestamp | Timestamp of last line item update, in UTC
Accepted values:`yyyy-mm-ddThh:mm:ss±hh:mm`(in ISO-8601)
Default: same as`createdAt`
Writeable? N / Nullable? N | (2) _Required for create operations_ **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. ## Flight Schedule Legs Attributes | Attribute | Data Type | Description | | --- | --- | --- | | `dayOfWeek` | enum | Day of the week or day type that the respective`leg`should be effective, i.e., the respective line item should be activated (in case all other conditions are satisfied)
Accepted values:`sunday`,`monday`,`tuesday`,`wednesday`,`thursday`,`friday`,`saturday`,`everyday`,`weekdays`,`weekends`
Writeable? Y / Nullable? N | | `startTime` | time | Start time that the respective`leg`should be effective, i.e., the respective line item should be activated (in case all other conditions are satisfied)
ℹ️ This time value will be interpreted considering the time zone provided in the`startDate`/`endDate`above
Accepted values:`hh:mm`, with values between`00:00`and`23:59`
Writeable? Y / Nullable? N | | `endTime` | time | End time that the respective`leg`should be effective, i.e., the respective line item should be deactivated (in case all other conditions are satisfied)
ℹ️ This time value will be interpreted considering the time zone provided in the`startDate`/`endDate`above
Accepted values:`hh:mm`, with values between`00:00`and`23:59`
Writeable? Y / Nullable? N | ## Get all Onsite Sponsored Products Line Items This endpoint lists all Onsite Sponsored Products line items in the specified campaign. This endpoint now returns `null` in the `budgetRemaining` field for line items with uncapped budgets and line items with missing budgets. Results are paginated using `offset` and `limit` query parameters; if omitted, defaults to `0` and `500`, respectively. See [API Response](https://developers.criteo.com/criteo-apis/docs/api-response#pagination). **Sample Request** cURL ```bash curl -L -X GET "https://api.criteo.com/{version}/retail-media/campaigns/544937665113018368/auction-line-items?offset=0&limit=500" \ -H "Authorization: Bearer " \ -H "Accept: application/json" ``` **Sample Response** ```json { "data": [ { "id": "9979917896105882144", "type": "SponsoredProductsLineItem", "attributes": { "name": "Line Item 123 Always On", "campaignId": "544937665113018368", "targetRetailerId": "12345", "startDate": "2024-09-01T04:00:00+00:00", "endDate": null, "status": "active", "budget": 5000.00, "budgetSpent": 2354.38, "budgetRemaining": 2645.62, "maxBid": 2.50, "targetBid": null, "monthlyPacing": null, "dailyPacing": null, "isAutoDailyPacing": false, "bidStrategy": "automated", "optimizationStrategy": "conversion", "flightSchedule": null, "keywordStrategy": "genericBrandedAndConquesting", "createdAt": "2024-08-24T15:46:45.1578781+00:00", "updatedAt": "2025-08-12T08:02:36.9158515+00:00" } }, // ... ], "metadata": { "count": 35, "offset": 0, "limit": 25 }, "warnings": [], "errors": [] } ``` ## Create an Onsite Sponsored Products Line Item This endpoint creates a new Onsite Sponsored Products line item in the specified campaign. **Retailer Budgets Campaigns**For retailer-budget campaigns, `targetRetailerId` must match the campaign’s `retailerId`. Mismatched values will return a `RetailerMismatchWithCampaign` error. **Sample Request** cURL ```bash curl -L -X POST '{version}/retail-media/campaigns/{campaignId}/auction-line-items' \ -H 'Content-Type: application/json' \ -H 'Accept: application/json' \ -H 'Authorization: Bearer ' \ -d '{ "data": { "type": "SponsoredProductsLineItem", "attributes": { "name": "My Retailer Budget Line Item", "targetRetailerId": "123", "startDate": "2026-06-01T00:00:00+00:00", "bidStrategy": "automated", "maxBid": 5.0, "optimizationStrategy": "conversion", "keywordStrategy": "genericAndBranded" } } }' ``` ## Update a Specific Onsite Sponsored Products Line Item This endpoint updates the specified Onsite Sponsored Products line item. **Sample Request** cURL ```bash curl -L -X PUT "https://api.criteo.com/{version}/retail-media/auction-line-items/6854840188706902009" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d '{ "data": { "id": "6854840188706902009", "type": "SponsoredProductsLineItem", "attributes": { "name": "Line Item 456 - Q4 Weekends Evenings", "campaignId": "544937665113018368", "targetRetailerId": "6789", "startDate": "2025-10-01T00:00:00-04:00", "endDate": "2025-12-31T23:59:59-04:00", "status": "active", "budget": 12000.00, "maxBid": 5.0, "targetBid": 1.0, "monthlyPacing": 4000.00, "isAutoDailyPacing": true, "flightSchedule": { "legs": [ { "dayOfWeek": "friday", "startTime": "18:00", "endTime": "23:59" }, { "dayOfWeek": "weekends", "startTime": "18:00", "endTime": "23:59" } ] } } } }' ``` **Sample Response** ```json { "data": { "id": "6854840188706902009", "type": "SponsoredProductsLineItem", "attributes": { "name": "Line Item 456 - Q4 Weekends Evenings", "campaignId": "544937665113018368", "targetRetailerId": "6789", "startDate": "2025-10-01T04:00:00+00:00", "endDate": "2026-01-01T03:59:59+00:00", "status": "draft", "budget": 12000.00, "budgetSpent": 0.00, "budgetRemaining": 12000.00, "maxBid": 5.0, "targetBid": 1.00000000, "monthlyPacing": 4000.00, "dailyPacing": 200.00, "bidStrategy": "manual", "optimizationStrategy": "conversion", "isAutoDailyPacing": true, "flightSchedule": { "legs": [ { "dayOfWeek": "friday", "startTime": "18:00", "endTime": "23:59" }, { "dayOfWeek": "weekends", "startTime": "18:00", "endTime": "23:59" } ] }, "keywordStrategy": "genericAndBranded", "createdAt": "2024-09-24T15:47:03.228224+00:00", "updatedAt": "2025-08-12T09:34:07.6168328+00:00" } }, "warnings": [], "errors": [] } ``` ## Responses | Response | Title | Description | | --- | --- | --- | | 🔵`200` | | Call completed with success | | 🔵`201` | | Line item created with success | | 🔴`400` | **Invalid`isAutoDailyPacing`** | Cannot turn on`IsAutoDailyPacing`and add a`dailyPacing`value. Only one of the two options can be used. | | 🔴`400` | **Conquesting not enabled** | `Conquesting`is not enabled for the specified retailer. Remove the`keywordStrategy`property from the creation request. | | 🔴`400` | `RetailerMismatchWithCampaign`
- Invalid Target Retailer | `targetRetailerId`on the line item doesn’t match the parent campaign’s`retailerId`. The`detail`field names both IDs: “Line item’s targetRetailerId does not match the retailer-billed campaign’s retailer ID ”. Ensure`targetRetailerId`on the line item matches the`retailerId`set on the parent campaign.