Search Line Items

Overview

The search endpoints let you retrieve line items in bulk by filtering on account, campaign, retailer, or line item IDs. Two variants are available depending on the account type you are operating from:

Demand search — query line items accessible from one or more demand accounts.
Supply search — query line items accessible from a supply account and its retailers.

Both endpoints are paginated and return the same line item shape in the response. Both endpoints require the RetailMedia_Campaign_Read scope.

Endpoints

Method	Endpoint	Description
`POST`	`/line-items/demand-search`	Search line items from demand accounts.
`POST`	`/line-items/supply-search`	Search line items from a supply account.

Search Line Items — Demand

Returns line items accessible from the specified demand accounts, with optional filters on campaign and line item IDs.

Request Attributes

Attribute	Required	Type	Description
`accountIds`	Yes	array of strings	One or more demand account IDs to search from.
`includeChildrenAccounts`	No	boolean	When `true`, includes line items from child or sub-accounts of the specified accounts.
`campaignIds`	No	array of strings	Filter results to line items belonging to these campaigns. Maximum 1,000 IDs.
`lineItemIds`	No	array of strings	Filter results to these specific line item IDs. Maximum 1,000 IDs.
`limit`	No	integer	Maximum number of results to return per page. Maximum 10,000.
`offset`	No	integer	Zero-based offset for pagination.

Sample Request

{
  "data": {
    "type": "DemandSearch",
    "attributes": {
      "accountIds": ["111222333"],
      "campaignIds": ["987654321"],
      "limit": 50,
      "offset": 0
    }
  }
}

Response Attributes

Results are returned as a paginated array under data. Each item contains:

Attribute	Type	Description
`lineItemId`	string	Unique identifier of the line item.
`name`	string	Display name of the line item.
`accountId`	string	The demand account the line item belongs to.
`campaignId`	string	The campaign the line item belongs to.
`retailerId`	string	The retailer associated with the line item.
`lineItemType`	string	Type of line item: `SponsoredProduct` or `OnsiteDisplay`.
`buyType`	string	Buy model: `Auction`, `PreferredDeals`, or `Sponsorship`.
`flightDates.startDate`	string	When the line item becomes active.
`flightDates.endDate`	string	When the line item expires.
`serveToOptOutUser`	boolean	Whether ads serve to users who opted out of personalization.
`conquestingSettings`	object	Keyword bidding strategy flags. See Create a Line Item Core for field descriptions.
`commerceDisplay.auction.isDynamicMatch`	boolean	Onsite Display Auction: whether dynamic matching is enabled.
`sponsoredProducts.auction.allInventory`	boolean	Sponsored Products Auction: whether all inventory is targeted.

The response also includes a metadata object with pagination fields:

Field	Description
`count`	Total number of line items matching the search.
`limit`	Page size used for this response.
`offset`	Offset used for this response.

Sample Response

{
  "data": [
    {
      "id": "112233445566778899",
      "type": "LineItem",
      "attributes": {
        "lineItemId": "112233445566778899",
        "name": "Back-to-school display",
        "accountId": "111222333",
        "campaignId": "987654321",
        "retailerId": "12345",
        "lineItemType": "OnsiteDisplay",
        "buyType": "Auction",
        "flightDates": {
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "serveToOptOutUser": false,
        "conquestingSettings": {
          "conquestingAdStrategyEnabled": false,
          "neutralAdStrategyEnabled": true,
          "defensiveAdStrategyEnabled": true,
          "isAdStrategyLocked": false
        },
        "commerceDisplay": {
          "auction": {
            "isDynamicMatch": true
          }
        }
      }
    }
  ],
  "metadata": {
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Errors

HTTP Status	Code	Description
`400`	`missing-request-body`	The request body is missing.
`400`	`invalid-campaign-id`	A campaign ID is invalid.
`400`	`invalid-line-item-id`	A line item ID is invalid.
`400`	`too-many-campaign-ids`	More than 1,000 campaign IDs were supplied.
`400`	`too-many-line-item-ids`	More than 1,000 line item IDs were supplied.
`400`	`invalid-offset`	`offset` is less than `0`.
`400`	`invalid-limit`	`limit` is outside the allowed range.
`401`	`unauthorized`	The caller is not authenticated.
`403`	`forbidden`	The caller does not have access to the requested accounts.

Search Line Items — Supply

Returns line items accessible from a supply account and its retailers, with optional filters on retailer, campaign, line item, and supply relationship.

Request Attributes

Attribute	Required	Type	Description
`supplyAccountId`	Yes	string	The supply account ID to search from.
`retailerIds`	Yes	array of strings	One or more retailer IDs to filter results by. At least one is required. Maximum 1,000 IDs.
`relationship`	No	string	Filter by supply relationship. Accepted values: `Direct`, `PrivateMarket`, `Network`, `AnyIndirect`. When omitted, all relationships are returned.
`campaignIds`	No	array of strings	Filter results to line items belonging to these campaigns. Maximum 1,000 IDs.
`lineItemIds`	No	array of strings	Filter results to these specific line item IDs. Maximum 1,000 IDs.
`limit`	No	integer	Maximum number of results to return per page. Maximum 10,000.
`offset`	No	integer	Zero-based offset for pagination.

Sample Request

{
  "data": {
    "type": "SupplySearch",
    "attributes": {
      "supplyAccountId": "444555666",
      "retailerIds": ["12345"],
      "relationship": "Direct",
      "limit": 50,
      "offset": 0
    }
  }
}

Response Attributes

Same shape as the demand search response. The metadata pagination object is also included. Sample Response

{
  "data": [
    {
      "id": "112233445566778899",
      "type": "LineItem",
      "attributes": {
        "lineItemId": "112233445566778899",
        "name": "Back-to-school display",
        "accountId": "111222333",
        "campaignId": "987654321",
        "retailerId": "12345",
        "lineItemType": "OnsiteDisplay",
        "buyType": "Auction",
        "flightDates": {
          "startDate": "2026-09-01T00:00:00Z",
          "endDate": "2026-09-30T23:59:59Z"
        },
        "serveToOptOutUser": false,
        "conquestingSettings": {
          "conquestingAdStrategyEnabled": false,
          "neutralAdStrategyEnabled": true,
          "defensiveAdStrategyEnabled": true,
          "isAdStrategyLocked": false
        },
        "commerceDisplay": {
          "auction": {
            "isDynamicMatch": true
          }
        }
      }
    }
  ],
  "metadata": {
    "count": 1,
    "limit": 50,
    "offset": 0
  }
}

Errors

HTTP Status	Code	Description
`400`	`missing-request-body`	The request body is missing.
`400`	`missing-supply-account-id`	`supplyAccountId` is missing from the request.
`400`	`invalid-supply-account-id`	`supplyAccountId` is not a valid ID.
`400`	`missing-retailer-ids`	`retailerIds` is missing or empty.
`400`	`invalid-retailer-id`	A retailer ID is invalid.
`400`	`invalid-relationship`	`relationship` is not an accepted value.
`400`	`invalid-campaign-id`	A campaign ID is invalid.
`400`	`invalid-line-item-id`	A line item ID is invalid.
`400`	`too-many-retailer-ids`	More than 1,000 retailer IDs were supplied.
`400`	`too-many-campaign-ids`	More than 1,000 campaign IDs were supplied.
`400`	`too-many-line-item-ids`	More than 1,000 line item IDs were supplied.
`400`	`invalid-offset`	`offset` is less than `0`.
`400`	`invalid-limit`	`limit` is outside the allowed range.
`401`	`unauthorized`	The caller is not authenticated.
`403`	`forbidden`	The caller does not have access to the requested supply account.

Introduction

Guides for Retail Media API

Overview

Endpoints

Search Line Items — Demand

Request Attributes

Response Attributes

Errors

Search Line Items — Supply

Request Attributes

Response Attributes

Errors

​Overview

​Endpoints

​Search Line Items — Demand

​Request Attributes

​Response Attributes

​Errors

​Search Line Items — Supply

​Request Attributes

​Response Attributes

​Errors

Overview

Endpoints

Search Line Items — Demand

Request Attributes

Response Attributes

Errors

Search Line Items — Supply

Request Attributes

Response Attributes

Errors