Create custom properties for collections

Collections include a predefined set of properties that store information about collections you use to organize your catalog.

This section applies to Open Storefront Framework (OSF) and Storefront Classic.

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 parameter expand=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.