Commerce Solutions API

The Trade Desk provides an API suite that enables commerce solutions to capture and organize item-level information for all types of merchants: advertisers who have a direct relationship with their end consumers or buy media on behalf of other advertisers, and data partners who collect user data and sell it to third parties to enrich their audiences for targeting and measurement purposes.

IMPORTANT: This API is designed for the workflow described in Product catalog integration. This guide is intended for all merchants interested in building data segments or providing measurement on The Trade Desk platform and bringing in their commerce data without using third-party data platforms. It also describes other integration options.

Merchants can use the Commerce Solutions endpoints to create product lists for their own use or allow specific brands or advertisers to use their catalog data. Advertisers can use the API to create product lists, whether those products are their own or provided by another merchant. They can then build segments for targeting and measure conversions (attribution) based on the users' activities on a merchant's website or in-store.

The following sections explain the organization and design of the commerce endpoints. If you are ready to upload your data, have the required access permissions, and know the expected workflow, you can begin building your catalog. Otherwise, see Product catalog integration.

REST API groups

There are several groups of the commerce endpoints that are distinguished by their intended usage. The following table lists the groups and provides links to the API reference sections and usage guidelines.

REST API Group and Endpoint Reference	Intended User	Description	Usage Guidelines
Merchant product category	All merchants	Create and manage product categories.	Building merchant product catalog
Merchant product	All merchants	Add and manage products in a catalog. Manage data access by product and by advertiser. TIP: Dynamic rules in the GraphQL API offer the most efficient way to grant and manage advertiser access to products in your catalog.	Merchant products Managing access to merchant product catalog
Merchant catalog access permission	All merchants	Manage advertisers' permissions to access product catalog data for audience building and measurement.	Catalog permissions
Advertiser product list	Brands and advertisers	Create and manage lists of products from a merchant's catalog for subsequent use in audience building and measurement.	Advertiser product lists
Advertiser product list tracking tag	Merchants Brands and advertisers	Retrieve tracking tags and their associated product lists.	Product list tracking tags

REST API usage overview

Here's what you need to know about the commerce endpoints when using them:

To enable you to create and manage multiple resources in a single request, most endpoints support batch operations, which is reflected in their path, for example, POST /ecommerce/category/batch/query.
The product and category PUT endpoints are upsert endpoints, which allow you to create new and update existing resources in a single request.
All PUT and DELETE endpoints are idempotent: if you pass the same ID multiple times in a request, they do not change the result beyond the initial application and return only one result. If you call DELETE endpoints multiple times, they may return a 404 (Not Found) error code after the first call.
All POST query endpoints return only one result if you pass the same ID multiple times in a request.
All batch endpoints support partial success and specify errors for the failed items in the response, using the following batch response structure.

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.

Batch response format

Most commerce APIs return batch responses in the following format:

{
   "BatchResponses":{
      "key1":{
          "Response":{}  // No errors.
      },
      "key2":{
         "Error":{
            "ErrorCode":"BadRequest",
            "Message":"Error code description."
         }
      }
   },
   "ContainsError":true
}

Property	Description
`BatchResponses`	A dictionary of key-value pairs with the following definitions: The key is a category, SKU, list, tracking tag, or other respective ID that identifies each `Response` object processed in a batch. The value is typically the `Response` object with the category, product, list, tracking tag, or other resource details, or an `Error` object with the failure details for the operation.
`ContainsError`	If set to `true`, indicates that at least one operation in the batch has failed, with the details provided in the `Error` object of the operation. If set to `false`, indicates that the entire request has been processed successfully.

NOTE: Some endpoints (noted in the respective user guides) return an empty BatchResponses object as a successful response, with the ContainsError property set to false. Otherwise, these endpoints return a BatchResponses object only with errors that occurred, as shown in the following section.

{
   "BatchResponses": {},
   "ContainsError": false
}

Batch response example

The following is an example of a product batch response with three objects in the batch. In this response, the key-value pairs are represented by product SKU IDs used as keys and two Response objects with product details and an Error object used as values.

{
   "BatchResponses":{
      "#2234567892":{
         "Response":{
            "SkuId":"#2234567892",
            "ProductName":"Chocolate & Vanilla Sandwich Cookies, 15.25 oz",
            "CategoryId":"1101",
            "BrandName":" Merchant Brand"
         }
      },
      "#4234567853":{
         "Error":{
            "ErrorCode": "BadRequest",
            "Message":"Product with SkuId: #4234567853 for MerchantId: GenericMartABC123 already exists."
         }
      },
      "#3234567894":{
         "Response":{
            "SkuId":"#3234567894",
            "ProductName":"Lemon Sandwich Creme Cookies, Family Size, 25 oz",
            "CategoryId":"1101",
            "BrandName":"Merchant Brand"
         }
      }
   },
   "ContainsError":true
}