Build custom taxonomy

IMPORTANT: You're this page because you're considering building a custom taxonomy. We recommend reusing an existing taxonomy from Google or Meta rather than building categories from scratch. If you decide to use an existing taxonomy, do not use the instructions here. For the end-to-end workflow, see Product catalog integration.

To build a structured, hierarchical product catalog, create a custom category taxonomy. Categories improve browsing, filtering, and reporting in your product catalog, but are optional. You can maintain a flat product list, if needed.

To define the taxonomy, choose one of the following options:

• Upload categories to the PUT /ecommerce/category/batch upsert endpoint.
• Use the product catalog feed URL integration for product information management (PIM) providers.
• Manually bulk upload using the UI template.

Before you begin, ensure you meet the following requirements and understand how the structure works.

Requirements

NOTE: If you are a location data provider, see Product catalog for location data providers. Location-based catalogs use the SKU ID, product name, brand, description, and category fields to represent locations and geographic groups.

• Creating categories is optional. You can maintain a flat product list without them.
• The category name is displayed in the UI and used for search and filtering.
• The category ID is used to retrieve, update, and delete categories, and to define relationships between them.

Structure and hierarchy

TIP: Before uploading categories, define category names, IDs, and parent-child relationships in a spreadsheet or visual hierarchy for reference.

Categories are organized into a hierarchy. Here's what you need to know:

• For more flexible hierarchies, associate product data with multiple categories.
• Categories themselves can have multiple parent categories (or none at all).
• When assigning parents, specify only the immediate parent categories. Higher-level ancestors are applied automatically.

The following diagram shows an example Food & Beverage root category. The product Cannoli di Sicilia appears in multiple categories, including Cannoli, Bakery, Dairy, and Food & Beverage. This allows products associated with Cannoli di Sicilia to appear under multiple category paths.

The following table shows an example product category hierarchy that you can reference when creating or updating categories.

The following table lists endpoints for managing categories. Each endpoint supports batch operations.

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

Upload product categories

To upload, send a PUT /ecommerce/category/batch request with your advertiser ID and, at minimum, the ID and name for each category.

{
  "AdvertiserId":"ADVERTISER_ID_PLACEHOLDER",
  "Categories":[
      {
         "CategoryId":"0000",
         "CategoryName":" Food & Beverages"
      },
      {
         "CategoryId":"1000",
         "CategoryName":"Bakery",
         "ParentCategories":[
            "0000"
         ]
      },
      {
         "CategoryId":"1104",
         "CategoryName":"Cannoli",
         "ParentCategories":[
            "1000",
            "3000"
         ]
      }
   ]
}

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 details, see Commerce Solutions API usage overview.

Get product category details

To get category names and parent IDs, send a POST /ecommerce/category/batch/query request with your merchant ID and the category IDs to look up, as shown in the following example.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "CategoryIds":[
      {
         "CategoryId":"2100"
      },
      {
         "CategoryId":"1102"
      }
   ]
}

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

Delete product categories

IMPORTANT: Before deleting a category, you must remove or reassign any associated products, and delete or reassign any child categories.

To delete categories, send a POST /ecommerce/category/batch/delete request with your merchant ID and the category IDs.

{
   "MerchantId":"MERCHANT_ID_PLACEHOLDER",
   "CategoryIds":[
      {
         "CategoryId":"1105"
      },
      {
         "CategoryId":"4000"
      }
   ]
}

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

Category batch response example

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

• PUT /ecommerce/category/batch (create or update) 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 category details, even on success.
• POST /ecommerce/category/batch/query (get) returns a BatchResponses object with a Response object containing category details for each requested category ID, as shown in the following example.

{
   "BatchResponses":{
      "1104":{
         "Response":{
            "CategoryId":"1104",
            "CategoryName":"Cannoli",
            "ParentCategories":[
               "1000",
               "3000"
            ]
         }
      },
      "2100":{
         "Response":{
            "CategoryId":"2100",
            "CategoryName":"Bottled Water",
            "ParentCategories":[
               "2000"
            ]
         }
      }
   },
   "ContainsError":false
}

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

Next steps

If you need to add location data taxonomy, see Location data. Otherwise, after creating your categories, upload your product data and associate products with the appropriate categories.