Line Item Core

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:

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.

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

{
  "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

{
  "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.

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.

{
  "data": {
    "type": "line-item",
    "attributes": {
      "name": "Back-to-school display — extended",
      "flightDates": {
        "endDate": "2026-10-15T23:59:59Z"
      },
      "isPaused": false
    }
  }
}

Sample Response

{
  "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.

Introduction

Guides for Retail Media API

Overview

Endpoints

Create a Line Item Core

Request Attributes

Errors

Update a Line Item Core

Path Parameters

Request Attributes

Errors

​Overview

​Endpoints

​Create a Line Item Core

​Request Attributes

​Errors

​Update a Line Item Core

​Path Parameters

​Request Attributes

​Errors

Overview

Endpoints

Create a Line Item Core

Request Attributes

Errors

Update a Line Item Core

Path Parameters

Request Attributes

Errors