commerce/catalog/admin/facets

Use the Facets resource to manage the facets shoppers use to filter product display results on a storefront. Facets can include categories, product attributes, or prices, and use either a range of values or discrete values.

JSON Example

Facet 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.

categoryId

type: int

ID of the relevant category.

facetId

type: int

Unique identifier of the facet.

facetType

type: string

The type of facet. Valid values are "range" (enables creation of a range of values) or "value" (populates the facet values based on the associated attribute or category).

isHidden

type: bool

Indicates if the object is hidden or breaks inheritance, primarily used by facets, products, and attribute vocabulary values. For example, if true, the attribute vocabulary value does not appear in the list when defining a value for an attribute.

order

type: int

Integer that represents the sequence order of the attribute.

overrideFacetId

type: int

Indicates the specific facet inherited from a parent category that is overridden by this facet. System-supplied and read only.

rangeQueries

type: list of facetRangeQuery

For range type facets, an array of ranges to use for the facet values. For example, a price facet might have range queries for $0-$25, $25-$50, and $50-$100.

facetRangeQuery.rangeValueEnd

type: object

The maximum value to use for the facet range query.

facetRangeQuery.rangeValueStart

type: object

The minimum value to use for the facet range query.

source

type: facetSource

Source for an action or container for originating content. Source is used as an origin for validation and notification messages based on successful or failed actions. For originating content, source is used for the facet source information, including the category, price, or attribute properties.

facetSource.allowsRangeQuery

type: bool

If true, the facet allows for values that consist of one or more ranges, such as 0-100, 100-200, and 200-300. This is only allowed for numeric and date fields.

facetSource.dataType

type: string

The data type of the source product property, typically of type Bool, DateTime, Number, or String.

facetSource.id

type: string

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

facetSource.name

type: string

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

facetSource.type

type: string

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

validity

type: facetValidity

System-supplied and read only indicator of whether a facet is currently valid and if not indicates the reason why. A facet may become invalid if the source data is changed in some ways (for example if the category tree structure is changed).

facetValidity.isValid

type: bool

Indicates if the facet is currently valid.

facetValidity.reasonCode

type: string

A code indicating the reason why a facet is invalid.

valueSortType

type: string

Determines how the facet values will be sorted in the store. Must be a valid value for DataType defined in FacetValueSortTypeConst. Allowable values are:

  • CountAscending
  • CountDescending
  • ValuesAscending
  • ValuesDescending
  • AttributeDefinition
  • AttributeDefinitionDescending

The default is AttributeDefinition.

Operations

Operation Name Request URI Description
AddFacet POST %3fresponseFields%3d%7bresponseFields%7d

Creates a new category, price, or attribute facet. Define the category or attribute source to use for the facet values.

DeleteFacetById DELETE %7bfacetId%7d

Deletes the facet specified by its unique identifier.

GetFacet GET %7bfacetId%7d%3fvalidate%3d%7bvalidate%7d%26responseFields%3d%7bresponseFields%7d

Retrieves a facet specified by its unique identifier and displays its properties.

GetFacetCategoryList GET category%2f%7bcategoryId%7d%3fincludeAvailable%3d%7bincludeAvailable%7d%26validate%3d%7bvalidate%7d%26responseFields%3d%7bresponseFields%7d

Retrieves a list of the facets defined for the specified category.

UpdateFacet PUT %7bfacetId%7d%3fresponseFields%3d%7bresponseFields%7d

Modifies one or more properties of a defined facet.