Merchant product lists

NOTE: This guide is intended only for brands or advertisers who are interested in targeting, retargeting, and measuring conversions (attribution) based on users' activities on a merchant's website.

Here's what you need to know before you can create lists of products from a product catalog against which to do measurement:

You need to have access to merchant data. Only merchants can grant you access to their products and check your permissions.
Merchants should provide you with their merchant ID, which you can look up in the URLs when accessing product catalogs via the platform UI.
You can create your lists in either of the following ways:
- Start from scratch: create one or more named lists and then adding products to each list.
- Clone one or more existing lists with product SKUs already added to them and then updating each list as needed.
You can add the same products to multiple lists.
Product list names and descriptions are displayed in the UI and can be used for search.
In the platform UI, product lists are referred to as itemsets.

IMPORTANT: All requests using the product list APIs require a valid advertiser ID and the merchant ID of the product catalog that you want to use for building audiences and measuring conversions.

Create product lists

This section outlines the overall process of creating product lists, with the subsequent sections providing details about specific endpoints required for each step.

IMPORTANT: All Commerce Solutions endpoints enforce a maximum of 1000 items per request. Payloads that exceed this limit will be rejected. To stay within the limit, split large datasets into multiple requests.

To create product lists for building audiences or measuring conversions using a merchant's product catalog data, complete the following steps:

Create one or more named product lists using the POST /v3/ecommerce/list/batch endpoint.
To each list, add product SKUs from the merchant's product catalog.
Create tracking tags for each of your product lists using the UI.

TIP: If you already have similar product lists, you can clone them and update their contents as needed.

After you create your product lists, you can update product list names and descriptions and contents (product SKUs) at any time. You can also use product lists to target and attribute with custom commerce segments and tracking tag IDs.

Manage product lists

The following table lists all tasks that you may need to perform when managing product list names and descriptions, as well as cloning and deleting product lists and their contents. For details on managing products in a list, see Manage list products.

IMPORTANT: All Commerce Solutions endpoints enforce a maximum of 1000 items per request. Payloads that exceed this limit will be rejected. To stay within the limit, split large datasets into multiple requests.

All of the following endpoints allow you to manage lists individually or in a batch.

Task	Endpoint	Notes
Create product lists.	POST /v3/ecommerce/list/batch	Creates lists with the specified names and optional descriptions. You still need to add product SKUs to each list.
Update product list names and descriptions.	PUT /v3/ecommerce/list/batch	Updates only product list names and descriptions. For details on updating products in a list, see Manage list products.
Get product list names and descriptions.	POST /v3/ecommerce/list/batch/query	Retrieves product list names, targeting segments, and descriptions. For details on retrieving products in a list, see Get product SKUs for list IDs.
Delete product lists.	POST /v3/ecommerce/list/batch/delete	Deletes entire product lists along with their contents. For details on deleting individual products from a list, see Remove product SKUs from a list.
Clone product lists and their contents.	POST /v3/ecommerce/list/batch/clone	Allows you to update names and descriptions for each new list. For details on updating products in new lists, see Manage list products.

Product list batch response example

A successful response to any of the product list endpoints returns a BatchResponses object with product list names, descriptions, and timestamps in the Response object for each list specified in the request.

{
   "BatchResponses":{
      "list1234":{  // For the create endpoint, this is the list name, not ID.
         "Response":{
            "ListId":"list1234",
            "ListName":"Merchant Brand Food and Beverages",
            "CreatedAtUtc":"2021-12-21T18:42:52.3910981+00:00",
            "LastUpdatedAtUtc":"2021-12-21T18:42:52.3910981+00:00"
         }
      },
      "list2345":{
         "Response":{
            "ListId":"list2345",
            "ListName":"Merchant Brand Produce",
            "ListDescription":"Fresh produce items",
            "CreatedAtUtc":"2021-12-21T18:42:52.3910981+00:00",
            "LastUpdatedAtUtc":"2021-12-21T18:42:52.3910981+00:00"
         }
      }
   },
   "ContainsError":false
}

Create product lists

To create one or more product lists, in a POST /v3/ecommerce/list/batch request, specify your advertiser ID and the merchant ID of the catalog from which you want to add products. For each list in the batch, provide a name and, optionally, a description of its intended contents.

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "Lists":[
      {
         "ListName":"Merchant Brand Food and Beverages"
      },
      {
         "ListName":"Merchant Brand Produce",
         "ListDescription":"Fresh produce items"
      }
   ]
}

A successful response returns a BatchResponses object with list details for each specified list.

For details on adding products to each list, see Add product SKUs to a list.

Update product list names and descriptions

To update the name or description of one or more product lists, in a PUT /v3/ecommerce/list/batch request, specify your advertiser ID, the merchant ID, and the IDs of the lists where you want to make changes.

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "Lists":[
      {
         "ListId":"list1234",
         "ListName":"Merchant Brand Food & Beverages",
         "ListDescription":"Packaged food and beverages"
      },
      {
         "ListId":"list2345",
         "ListName":"Merchant Brand Fresh Produce"
      }
   ]
}

A successful response returns a BatchResponses object with updated list details for each list ID.

For details on updating products in a list, see Manage list products.

Get product list names and descriptions

To retrieve the name, description, and creation and last update timestamps of one or more product lists, in a POST /v3/ecommerce/list/batch/query request, specify your advertiser ID, the merchant ID, and the IDs of the lists that you want to look up.

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "ListIds":[
      {
         "ListId":"list1234"
      },
      {
         "ListId":"list2345"
      }
   ]
}

A successful response returns a BatchResponses object with list details for each list ID.

For details on retrieving products in a list, see Get product SKUs for list IDs.

Delete product lists

To delete one or more product lists along with their contents, in a POST /v3/ecommerce/list/batch/delete request, specify your advertiser ID, the merchant ID, and the IDs of the lists that you want to delete.

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "ListIds":[
      {
         "ListId":"list1234"
      },
      {
         "ListId":"list2345"
      }
   ]
}

A successful response returns a BatchResponses object with list details for each list ID.

For details on deleting individual products from a list, see Remove product SKUs from a list.

Clone product lists

To clone one or more product lists along with their contents, in a POST /v3/ecommerce/list/batch/clone request, specify your advertiser ID, the merchant ID, and the IDs of the lists that you want to clone.

For example, the following request creates two lists from the Food & Beverages list:

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "CloneContexts":[
      {
         "SourceListId":{
            "ListId":"list1234"
         },
         "NewList":{
            "ListName":"Merchant Brand Food",
            "ListDescription":"Groceries and pre-packaged food, no drinks"
         }
      },
      {
         "SourceListId":{
            "ListId":"list1234"
         },
         "NewList":{
            "ListName":"Merchant Brand Beverages",
            "ListDescription":"All non-alcoholic beverages"
         }
      }
   ]
}

A successful response returns a BatchResponses object with list details for each new list.

For details on updating products in new lists, see Manage list products.

Manage list products

The following table lists all tasks that you may need to perform when managing products in lists.

Task	Endpoint	Notes
Add product SKUs to a list.	PUT /v3/ecommerce/list/products/add	N/A
Get product SKUs for one or more specified list IDs.	POST /v3/ecommerce/list/sku/batch/query	N/A
Remove product SKUs from a list.	PUT /v3/ecommerce/list/products/remove	For details on deleting an entire list, see Delete product lists.

Add product SKUs to a list

To add one or more product SKUs from a merchant's catalog to a list, in a PUT /v3/ecommerce/list/products/add request, specify your advertiser ID, the merchant ID, the list ID, and the SKU IDs of the products that you want to add.

NOTE: If a SKU is already added to the list, it isn't duplicated, and no error is returned.

Here's an example of a PUT /v3/ecommerce/list/products/add request:

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "ListId":"list1234",
   "SkuIds":[
      {
         "SkuId":"#3234567894"
      },
      {
         "SkuId":"#2234567892"
      },
      {
         "SkuId":"#1234567890"
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. Otherwise, the response includes a BatchResponses object with errors that occurred.

Get product SKUs for list IDs

To retrieve SKU IDs of all products added to one or more product lists, in a POST /v3/ecommerce/list/sku/batch/query request, specify your advertiser ID, the merchant ID, and the IDs of the lists where you want to look up products.

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "ListIds":[
      {
         "ListId":"list1234"
      },
      {
         "ListId":"list2345"
      }
   ]
}

A successful response returns a BatchResponses object with product SKUs excluded from the specified list.

{
   "BatchResponses":{
      "1":{
         "Response":[
            "#3234567894",
            "#2234567892",
            "#1234567890"
         ]
      },
      "2":{
         "Response":[
            "#3547567899",
            "#2344567765",
            "#7384567899",
            "#1354567765",           
            "#0974561846"
         ]
      }
   },
   "ContainsError":false
}

Remove product SKUs from a list

To remove one or more product SKUs from a product list, in a PUT /v3/ecommerce/list/products/remove request, specify your advertiser ID, the merchant ID, the list ID, and the SKU IDs of the products that you want to remove.

To delete an entire list, see Delete product lists.
To look up SKU IDs of the products added to the list, see Get product SKUs for list IDs.

Here's an example of a PUT /v3/ecommerce/list/products/remove request:

{
   "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "ListId":"list1234",
   "SkuIds":[
      {
         "SkuId":"#3234567894"
      },
      {
         "SkuId":"#2234567892"
      },
      {
         "SkuId":"#1234567890"
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. Otherwise, the response includes a BatchResponses object with errors that occurred.

Audience targeting

Advertisers can build custom commerce segments from merchant product lists and targeting data. These custom segments can be used as seeds for audience targeting. Use the Platform API to bulk create multiple segments from a product list and apply expansion to fine-tune reach.

Here's what you need to know about targeting data:

You can use first-party or third-party commerce data.
You must define segment rules in the SegmentRuleType and SegmentRuleValue properties to rank audiences.
Rankings are based on audience event frequency, top customer percentile, or audience monetary value. For details on segment rule types and values, see the POST /v3/ecommerce/list/targetingdata.
You can enable segment expansion by providing a list of segment expansion types in the SegmentExpansion property.
Bulk create multiple segments by adding more items in the list of targeting data.
First-party data segments returned belong to The Trade Desk as a third-party data owner.
Commerce segments returned belong to the same commerce data provider.

Create segments from product lists

To create a segment from a product list, use the POST /v3/ecommerce/list/targetingdata endpoint and include the IDs of your advertiser, product catalog, merchant, and a list of targeting data.

For example, the following request creates multiple expanded custom segments from a product list:

{
  "AdvertiserId": "xjagv7s",
  "ListId": "7667",
  "MerchantId": 1002,
  "TargetingData": [
    {
      "EventName": "addtocart",
      "RecencyWindowInDays": 90,
      "DataOwnerType": "ThirdParty",
      "SegmentRuleValue": 1,
      "SegmentRuleType": "EventFrequency",
      "SegmentExpansions": [ "Precise", "Balanced" ]
    }
  ]
}

A successful response returns an empty BatchResponses object.

IMPORTANT: To view created segments, use the POST /v3/ecommerce/list/batch/query.

Next steps

To target audiences with custom commerce segments, you must have a seed or audience. For details, see Building audiences and Seeds.

If you're interested, you can create tracking tags for product lists and retrieve their details through the platform UI or Custom Solutions API. For details, see Product list tracking tags.