The Categories resource provides access to categories that are available to a shopper. Categories are used to organize products in a catalog. A catalog is a collection of products that have been organized into meaningful groups called categories for a store. Catalogs are created at the site-level and categories are created within a catalog. To view a diagram and more information about the hierarchical relationship between site, catalogs, categories, and products, see Company Hierarchy Overview.

When you get a category, the API returns links to the products within the category. To get all of the products for a category, you can either use the expand=product query parameter or you can make follow-up calls.

Categories can be nested; that is, contain subcategories. Getting products for a category returns products for that level of category and subcategories one level deep.

Use the Categories resource to:

  • Retrieve all top-level categories and subcategories one level deep
  • Get a category by its specific id
  • Get all products for a category

A list of the Categories resource methods is available below, with links to the details for each method. The URL structures and the relationships between related resources are shown in the diagram below. Click the thumbnail to view an enlarged image.


GET shoppers/me/categories

Gets all top-level categories and subcategories nested one level deep.

GET shoppers/me/categories/{id}

Get a category by id. Specify the id of the category in the {id} uri path parameter.

GET shoppers/me/categories/{id}/products

Retrieve all products for a category. Specify the id of the category in the {id} uri path parameter.


FieldData TypeVisibilityDescription

A collection of categories in the category, also referred to as subcategories.

customAttributes collectionexpand

A collection of the custom attributes configured for the category. Custom attributes are not included with the resource by default. Expanding the customAttributes returns all of the configured attributes for the category.

customAttributes.attribute stringexpand

A specific custom attribute configured for a category. The attribute consists of a name, type, and a value. Use expand customAttributes.{name} to retrieve specific custom attributes for a category. 


The name of the category to display to the shopper.


The category id. The id is assigned automatically when the category is created.


The locale defined for the category.

longDescription stringdefault

A detailed description of the category.

name stringdefault

The name of the category.

products linkdefault

The products in the category. For more information, see the Products resource.

shortDescription stringdefault

A brief description of the category.

thumbnailImage uridefault

A URI to the thumbnail image of the category.