commerce/catalog/admin/categories

Use the Categories resource to organize products and control where they appear on the storefront. Create and maintain a hierarchy of categories and subcategories where the site will store properties.

JSON Example

Category Properties

Property Description
auditInfo

type: auditInfo

Basic audit info about the object, including date, time, and user account. This data may be captured when creating, updating, and removing data.

auditInfo.createBy

type: string

Identifier of the user that created the object. System created and read only.

auditInfo.createDate

type: DateTime

The date and time in UTC format set when the object was created.

auditInfo.updateBy

type: string

Identifier of the user that updated the entity most recently.

auditInfo.updateDate

type: DateTime

The date and time in UTC format the object was updated most recently.

catalogId

type: int

The unique identifier for the product catalog. Catalogs are part of a master catalog.

categoryCode

type: string

External unique identifier of the category.

categoryType

type: string

Specifies the type of category. The following are the valid values:

  • Static
  • DynamicPreComputed
  • DynamicRealTime
Note:  You cannot change this value for already existing categories.

childCount

type: int

The number of children (subcategories, for example) that stem from a parent (top-level category).

content

type: categoryLocalizedContent

Localizable content (such as a name and/or description) for an attribute. The content may be localized when displayed according to the locale code specified by the master catalog. Content can include descriptive text for product extensible attributes, catalog-level descriptions (displayed if isContentOverriden is true), product bundles, and customer account notes.

categoryLocalizedContent.categoryImages

type: list of categoryLocalizedImage

Array list of media images associated to a product category. These images may be localized in the language specified by the LocaleCode. Images display with the category on the storefront according to the code and formatting of your site theme. Each image includes the name, alt text, and URL location.

categoryLocalizedContent.categoryLocalizedImage.altText

type: string

Descriptive text associated with the image or video that appears on the web storefront. This text displays on a hover-over in the browser, providing further information on the content displayed. The alternate text should be plain alphanumeric text without special characters or HTML coding.

categoryLocalizedContent.categoryLocalizedImage.cmsId

type: string

The identifier of the image in the Kibo eCommerce CMS. Supply a value for either the CMS ID or Image URL parameter.

categoryLocalizedContent.categoryLocalizedImage.id

type: int

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

categoryLocalizedContent.categoryLocalizedImage.imageLabel

type: string

The localized title for an image that displays on the storefront. If localized, the displayed content is set per the locale code for the site.

categoryLocalizedContent.categoryLocalizedImage.imageUrl

type: string

The URL link for the image file associated with a product or category.

categoryLocalizedContent.categoryLocalizedImage.localeCode

type: string

The two character locale code, per the country code provided. This code determines the localized content to use and display.

categoryLocalizedContent.categoryLocalizedImage.mediaType

type: string

Type of media specification required to successfully render the image, video, or other media content for products and categories.

categoryLocalizedContent.categoryLocalizedImage.sequence

type: int

The numeric order of objects, used by a vocabulary value defined for an extensible attribute, images, and categories.

categoryLocalizedContent.categoryLocalizedImage.videoUrl

type: string

The URL of a video files for a product or category. The path name is set in the language specified by the LocaleCode.

categoryLocalizedContent.description

type: string

The localized description in text for the object, displayed per the locale code. For example, descriptions are used for product descriptions, attributes, and pre-authorization transaction types.

categoryLocalizedContent.localeCode

type: string

The two character locale code, per the country code provided. This code determines the localized content to use and display.

categoryLocalizedContent.metaTagDescription

type: string

Description defined for metadata, used to interally manage data, in the language specified by the `localeCode`. This content is used by categories, products, localized content, and SEO content.

categoryLocalizedContent.metaTagKeywords

type: string

Keywords defined for metadata, used to internally manage data, in the language specified by the `localeCode`. Keywords are used by content for categories, products, localized content, and SEO content.

categoryLocalizedContent.metaTagTitle

type: string

Title defined for metadata, used to internally manage data, in the language specified by the `localeCode`. Titles are used by content for categories, products, localized content, and SEO content.

categoryLocalizedContent.name

type: string

The user supplied name that appears in Admin. You can use this field for identification purposes.

categoryLocalizedContent.pageTitle

type: string

Title that appears on new product category pages, in the language specified by the `localeCode`.

categoryLocalizedContent.slug

type: string

Slug is used in place of a name, code, or ID to give an SEO, human-friendly URL link for an object, used by categories.

dynamicExpression

type: dynamicExpression

The expression that controls the product membership of the dynamic category. This field is only applicable when the categoryType is set to either "DynamicPreComputed" or "DynamicRealTime".

Refer to Dynamic Category Expressions for more information about writing dynamic expressions using the Kibo eCommerce API.

dynamicExpression.text

type: string

The text view of the dynamic expression. For example, instead of writing a structure JSON object, you can write a simple string as the dynamic expression.

dynamicExpression.tree

type: expression

The tree view of the dynamic expression. This is a structure JSON object that gives you greater control and flexibility over the text view when writing the dynamic expression.

dynamicExpression.expression.left

type: string

The expression field you wish to target. For example, if you wish to target the productCode field, this value would be productCode.

Refer to Dynamic Category Expressions for more information about the supported expression fields.

dynamicExpression.expression.logicalOperator

type: string

The logical operator you wish to perform on the nodes within the dynamic expression. Valid values are: "And", and "Or".

dynamicExpression.expression.nodes

type: list of Mozu.ProductAdmin.Contracts.Expression

The node or container of the self-contained dynamic expression. The node contains the following expression fields in order: "type", "left", "operator", and "right".

For example, a dynamic expression that specifies to include all products that are in the apparel category would have the following node:

"type": "predicate", "left": "Categories.CategoryCode", "operator": "eq", "right": "apparel".

dynamicExpression.expression.operator

type: string

The operator you wish to perform on the left field. The valid values of this field are dependent on the left expression field. Refer to Dynamic Category Expressions for more information about the supported expression field operators.

dynamicExpression.expression.right

type: object

The literal values of the predicate that is validated against the combined values of the left and operator fields.

For example, you wish to validate on products that have a product code of "shoe". You would write the following expression:

"type": "predicate", "left": "productCode", "operator": "eq", "right": "shoe".

dynamicExpression.expression.type

type: string

The type of scope, which is a developer account or production tenant.

id

type: int

Unique identifier of the source property, such as a catalog, discount, order, or email template.

For a product field it will be the name of the field.

For a category ID, must be a positive integer not greater than 2000000. By default, Kibo eCommerce auto-generates a category ID when categories are created. If you want to specify an ID during creation (which preserves category link relationships when migrating tenant data from one sandbox to another), you must also include the useProvidedId query string in the endpoint. For example, api/commerce/catalog/admin/categories/?useProvidedId=true. Then, use the id property to specify the desired category ID.

For a product attribute it will be the Attribute FQN.

For a document, the ID must be specified as a 32 character, case-insensitive, alphanumeric string. You can specify the ID as 32 sequential characters or as groups separated by dashes in the format 8-4-4-4-12. For example, bba0a1a885e2413bb097ceacf7bac366
or
bba0a1a8-85e2-413b-b097-ceacf7bac366.

For email templates, the ID must be one of the following values:
BackInStock
OrderChanged
OrderShipped
OrderFulfillmentDetailsChanged
ShopperLoginCreated
ShopperPasswordReset
ReturnCreated
ReturnAuthorized
ReturnUpdated
ReturnRejected
ReturnCancelled
ReturnClosed
RefundCreated
StoreCreditCreated
StoreCreditUpdated
GiftCardCreated

isActive

type: bool

Indicates if the object or feature is active.

isDisplayed

type: bool

Indicates if the object is displayed on the storefront. If true, the admin product category is displayed in the store. If false, the category is not displayed.

parentCategoryCode

type: string

The code of the current category's parent category.

parentCategoryId

type: int

If the current category has a parent, the identifier of the category's parent category.

parentCategoryName

type: string

If the current category has a parent, the name of the category's parent category.

parentIsActive

type: bool

Indicates whether the parent category is active.

productCount

type: int

The total number of products. This total may indicate the total products associate with a product type or number of products in a list.

sequence

type: int

The numeric order of objects, used by a vocabulary value defined for an extensible attribute, images, and categories.

Operations

Operation Name Request URI Description
AddCategory POST %3fincrementSequence%3d%7bincrementSequence%7d%26useProvidedId%3d%7buseProvidedId%7d%26responseFields%3d%7bresponseFields%7d

Adds a new category to the site's category hierarchy.

Specify a parentCategoryId to determine where to place the category in the hierarchy. If no parentCategoryId is specified, the new category is a top-level category.

AddProductsToCategory POST %7bcategoryId%7d%2fadd-products

admin-categories Post AddProductsToCategory description DOCUMENT_HERE

DeleteCategoryById DELETE %7bcategoryId%7d%2f%3fcascadeDelete%3d%7bcascadeDelete%7d%26forceDelete%3d%7bforceDelete%7d%26reassignToParent%3d%7breassignToParent%7d

Deletes the specified category. Use the categoryId parameter to specify the category.

GetCategories GET %3fstartIndex%3d%7bstartIndex%7d%26pageSize%3d%7bpageSize%7d%26sortBy%3d%7bsortBy%7d%26filter%3d%7bfilter%7d%26responseFields%3d%7bresponseFields%7d

Retrieves a list of categories according to any specified filter criteria and sort options.

GetCategory GET %7bcategoryId%7d%3fresponseFields%3d%7bresponseFields%7d

Retrieves the details of a single category.

GetChildCategories GET %7bcategoryId%7d%2fchildren%3fresponseFields%3d%7bresponseFields%7d

Retrieves the list of subcategories within a category.

RemoveProductsFromCategory POST %7bcategoryId%7d%2fremove-products

admin-categories Post RemoveProductsFromCategory description DOCUMENT_HERE

UpdateCategory PUT %7bcategoryId%7d%3fcascadeVisibility%3d%7bcascadeVisibility%7d%26responseFields%3d%7bresponseFields%7d

Update the properties of a defined category or move it to another location in the category hierarchy. Because this operation replaces the defined resource,include all the information to maintain for the category in the request.

ValidateDynamicExpression POST ValidateDynamicExpression%3fresponseFields%3d%7bresponseFields%7d

Validate the precomputed dynamic category expression for correctness.

ValidateRealTimeDynamicExpression POST ValidateRealTimeDynamicExpression%3fresponseFields%3d%7bresponseFields%7d

Validates the readltime dynamic category expression for correctness.