Create custom properties for collections
Collections include a predefined set of properties that store information about collections you use to organize your catalog.
In addition to these predefined properties, you can create custom collection properties. This section describes how to use the Commerce Admin REST APIs to add custom properties to collections. See Use the REST APIs for information you need to know before using the APIs.
Understand item types
Item types are templates for Commerce assets, such as collections and promotions. They contain properties that describe the asset.
The category
item type lets you work with the collections in a Commerce catalog. You can use the updateItemType
endpoint to modify the
category
item type. You can modify existing properties by changing the
values of their attributes and create custom properties by specifying their attributes.
SeeSettable attributes of shopper type properties for
descriptions of these attributes. The next section provides an example of creating a custom
property for collections.
Create a custom collections property
To add custom properties to the category
item type, issue a PUT
request to the /ccadmin/v1/itemTypes/category
endpoint on the administration server.
Use the following format:
- The request header must specify the
x-ccasset-language
value. - The request body is a map where each key is the ID of a new property, and each value is an object that specifies the values of the attributes of the property.
- Each object is also a map, with each key being the name of an attribute and each value being the corresponding attribute value.
Note that the ID of a custom property must include the underscore character (_). This ensures that the ID will not conflict with any properties that Commerce adds to item types in the future. The endpoint returns an error if you attempt to create a custom property without an underscore in its ID.
Remember to publish the new property once it is successfully created. See Publish Changes for more information.
The following example shows a sample request for adding a custom text property to the category
item type:
PUT /ccadmin/v1/itemTypes/category HTTP/1.1
Authorization: Bearer <access_token>
x-ccasset-language: en
Content-Type: application/json
{
"specifications": [
{
"id": "_myNewProperty",
"label": "My New Property",
"type": "shortText",
"required": false,
"uiEditorType": "shortText",
"uiwritable": "true",
"localizable": false,
"hidden": false,
"propertySortPriority": "100"
}
]}
The response includes the property you created.
...
{
"hidden": false,
"length": 254,
"label": "My New Property",
"type": "shortText",
"required": false,
"searchable": false,
"writable": true,
"internalOnly": false,
"uiEditorType": "shortText",
"default": null,
"audienceVisibility": null,
"localizable": false,
"textSearchable": false,
"id": "_myNewProperty",
"dimension": false,
"propertySortPriority": "100",
"editableAttributes": [
"internalOnly",
"default",
"audienceVisibility",
"hidden",
"textSearchable",
"label",
"dimension",
"propertySortPriority",
"required",
"searchable"
]
}
...
When you add a custom property to the category item type, the property is added to all collections, including any new collections you create and any collections that already exist. It appears on the General tab of every collection's details page in the administration interface. Business users can view, add, and edit values for custom collection properties, just as they do for predefined properties. (See Organize products in collections for more information.) Custom collection properties themselves cannot be edited in the administration interface; you can perform these tasks only with the Admin API.
Access custom collections properties
Storefront and Agent Console developers can access custom properties of the category
item type with the following Store API and Agent API endpoints:
getCollection
returns a collection by ID.listCollections
returns a list of collections by a list of IDs.listItemTypes
returns information about item types by a list of IDs.getItemType
returns information about an item type by ID.getPage
returns a specific page. For category page responses, custom properties are also returned as part of the response.
Keep the following points in mind when accessing custom properties with Store or Agent endpoints:
- If a custom property is specified as internal only (by setting the attribute
internalOnly=true
when you create the property), it will not be returned by any Store endpoints. - Custom properties appear at the top level of the response.
- Only
getCollection
returns custom properties for child collections. The request must include the parameterexpand=childCategories
. For example:GET /ccstore/v1/collections/rootCategory?catalogId=storefrontCatalog&maxLevel=1000&expand=childCategories&fields=childCategories%28items%29
- There is no view model support for custom properties of the
category
item type.