Upload product catalog data using Commerce Solutions API

After setting up your taxonomy, you can use the following API endpoints to upload and manage product data by SKU ID, or rename custom fields. To optimize the catalog, provide as many product attributes as possible when uploading data.

The following table lists tasks and endpoints for managing product data. Each endpoint supports batch operations.

Task	Endpoint	Notes
(Optional) Rename custom fields.	`merchantCustomColumnContextUpdate` mutation	This is a GraphQL mutation, unlike the other endpoints in this table, which use REST.
Upload product data.	PUT /ecommerce/product/batch	This is a batch upsert endpoint. Product data used in an active list by a brand or advertiser cannot be modified.
Get product details.	POST /ecommerce/product/batch/query	Retrieves product details for specified SKU IDs.
Delete product data.	POST /ecommerce/product/batch/delete	Product data used in an active list by a brand or advertiser cannot be deleted.

A successful response format depends on the endpoint. PUT /ecommerce/product/batch returns an empty BatchResponses object on success; POST /ecommerce/product/batch/query returns category details. For examples, see the Product data batch response example.

(Optional) Rename custom fields

Custom fields are automatically created when you define your taxonomy and create your product catalog. These fields can capture additional product data, such as promotion details or supplier-specific metadata. By default, they are assigned placeholder names. To make them easier to identify in the UI and reports, assign human-readable names and descriptions using the merchantCustomColumnContextUpdate GraphQL mutation or the Merchant Onboarding Tool UI.

NOTE: You can configure up to 10 optional custom fields, including five string fields and five numeric fields.

Here's an example merchantCustomColumnContextUpdate mutation that updates the names and descriptions of a custom field and a custom numeric field.

mutation {
  merchantCustomColumnContextUpdate(
    merchantId: MERCHANT_ID_PLACEHOLDER
    merchantCustomColumnContextUpdateInput: {
      customName1: "Promo type"
      customDescription1: "Type of promotion applied to the product, e.g. clearance or seasonal"
      customNumericName2: "Promo discount"
      customNumericDescription2: "Discount percentage applied under the current promotion, e.g. 0.15 for 15%"
    }
  ) {
    data {
      customName1
      customDescription1
      customNumericName2
      customNumericDescription2
    }
    errors {
      __typename
      ... on MutationError {
        field
        message
      }
    }
  }
}

Upload product data in a catalog

To upload product data, send a PUT /ecommerce/product/batch request with your merchant ID and, at minimum, a SKU ID and name for each product.

TIP: To improve product discoverability and usability in the catalog, provide as many attributes as possible (for example, images, descriptions, and brand names).

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "Products":[
      {
         "SkuId":"#1234567890",
         "ProductName":"Pre-Sliced Plain Bagels, 18 oz, 6 count",
         "CategoryId":"1100",
         "BrandName":"Merchant Brand",
         "ImageLink":" https://i5.genericmartimages.com/asr/xxxx134-.jpeg?odnHeight=450&odnWidth=450&odnBg=ffffff",
         "Availability":"in stock",
         "Description":"Merchant Brand pre-sliced plain bagels are baked to perfection. Enjoy them toasted and spread with cream cheese or serve with scrambled eggs and crispy bacon strips. These bagels are perfect for breakfast, but you could savor them any time of the day."
      },
      {
         "SkuId":"#2234567892",
         "ProductName":"Chocolate & Vanilla Sandwich Cookies, 16 oz",
         "CategoryId":"1101",
         "BrandName":"Merchant Brand"
      },
      {
         "SkuId":"#3234567894",
         "ProductName":"Lemon Sandwich Creme Cookies, Family Size, 25 oz",
         "CategoryId":"1101",
         "BrandName":" Merchant Brand",
         "Description":"These mouthwatering treats combine crispy lemon cookies with a smooth and creamy filling, giving you bright citrus flavor and a pleasing mix of textures in every bite. The family size tray is ideal for sharing at all your family meals, friendly gatherings, picnics, or outdoor events."
      }
   ]
}

A successful response returns an empty BatchResponses object with the ContainsError property set to false. If there are errors, the response includes details for each failed item. For more information, see Commerce Solutions API usage overview.

Get product details

To retrieve product details, send a POST /ecommerce/product/batch/query request with your merchant ID and the SKU ID.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "SkuIds":[
      {
         "SkuId":"#2234567892"
      },
      {
         "SkuId":"#3234567894"
      }
   ]
}

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

Delete product data from a catalog

To delete product data, send a POST /ecommerce/product/batch/delete request with your merchant ID and the SKU IDs.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "SkuIds":[
      {
         "SkuId":"#3234567894"
      },
      {
         "SkuId":"#5334567897"
      }
   ]
}

Product data batch response example

The response format for product endpoints varies depending on the endpoint:

PUT /ecommerce/product/batch (upload) returns an empty BatchResponses object with ContainsError set to false on success. If any items fail, the response includes an Error object only for the failed items. It never includes product details, even on success.
POST /ecommerce/product/batch/query (get) returns a BatchResponses object with a Response object containing product details for each requested SKU ID, as shown in the following example.

{
   "BatchResponses":{
      "#2234567892":{
         "Response":{
            "SkuId":"#2234567892",
            "ProductName":"Chocolate & Vanilla Sandwich Cookies, 16 oz",
            "CategoryId":"1101",
            "BrandName":"Merchant Brand"
         }
      },
      "#3234567894":{
         "Response":{
            "SkuId":"#3234567894",
            "ProductName":"Lemon Sandwich Creme Cookies, Family Size, 25 oz",
            "CategoryId":"1101",
            "BrandName":"Merchant Brand",
            "Description":"These mouthwatering treats combine crispy lemon cookies with a smooth and creamy filling, giving you bright citrus flavor and a pleasing mix of textures in every bite. The family size tray is ideal for sharing at all your family meals, friendly gatherings, picnics, or outdoor events."
         }
      }
   },
   "ContainsError":false
}

For details on the response format, see Commerce Solutions API usage overview.

Next steps

After uploading your product data, select the type of event data you plan to send with product data:

Offline conversion events
Real-time conversion events