Response filters provide an alternative way to use the fields
and exclude
query parameters. Rather than using fields
or exclude
to explicitly list properties in the URL of a REST call, you can create persistent filters that store the set of properties to include or exclude. You can then specify a filter by name in the URL using the filterKey
query parameter. For example, you could create a response filter named productSummary
that lists product properties to include, and then invoke the filter like this:
GET /ccadmin/v1/products?filterKey=productSummary
Note: A response filter is essentially a wrapper for the fields
and exclude
query parameters, and the properties returned by a filter are the same as they would be for equivalent fields
and exclude
expressions. If you include the filterKey
query parameter and either fields
or exclude
(or both) in an API call, filterKey
is ignored, and fields
and exclude
are applied.
To view a list of response filters, use the listFilters
endpoint in the Admin API:
GET /ccadmin/v1/responseFilters HTTP/1.1
Authorization: Bearer <access_token>
Note that by default there are four response filters included with Commerce Cloud:
{ "links": [ { "rel": "self", "href": "http://myserver.example.com:7002/ccadmin/v1/responseFilters" } ], "items": [ { "include": "items.id,items.displayName,items.type,items.variantValuesOrder, items.productVariantOptions,items.defaultProductListingSku, items.dynamicPropertyMapLong,items.route,items.primarySmallImageURL, items.primaryImageAltText,items.primaryImageTitle,items.childSKUs, items.listPrice,items.salePrice,items.relatedProducts, category.displayName,items.description,totalResults,offset, totalExpandedResults", "exclude": "items.childSKUs.largeImage,items.childSKUs.largeImageURLs, items.childSKUs.fullImageURLs,items.childSKUs.listPrices, items.childSKUs.mediumImageURLs,items.childSKUs.primaryLargeImageURL, items.childSKUs.primaryMediumImageURL, items.childSKUs.primaryThumbImageURL,items.childSKUs.thumbImageURLs, items.childSKUs.salePrices,items.childSKUs.thumbnailImage, items.childSKUs.barcode,items.childSKUs.denomination, items.childSKUs.model,items.childSKUs.productFamily, items.childSKUs.productLine,items.childSKUs.unitOfMeasure, items.childSKUs.saleVolumePrices", "key": "PLPData" }, { "include": "childCategories(items).displayName,childCategories(items).route, childCategories(items).id, childCategories(items).childCategories.displayName, childCategories(items).childCategories.route, childCategories(items).childCategories.id, childCategories(items).childCategories.childCategories.displayName, childCategories(items).childCategories.childCategories.route, childCategories(items).childCategories.childCategories.id, childCategories(items).childCategories.childCategories.childCategories", "key": "categoryNavData" }, { "include": "items.id,items.displayName,items.productVariantOptions, items.defaultProductListingSku,items.dynamicPropertyMapLong, items.route,items.primarySmallImageURL,items.primaryImageAltText, items.primaryImageTitle,items.childSKUs.listPrice, items.childSKUs.salePrice,items.listPrice,items.salePrice, items.relatedProducts,items.childSKUs.dynamicPropertyMapLong, items.childSKUs.repositoryId,category.displayName,items.description", "key": "collectionData" }, { "include": "id,active,saleVolumePrices,listVolumePrices,route,configurable, dynamicPropertyMapLong,productVariantOptions,primaryThumbImageURL, notForIndividualSale,displayName,childSKUs.repositoryId, childSKUs.active,childSKUs.listPrice,childSKUs.salePrice, childSKUs.primaryThumbImageURL,childSKUs.listingSKUId, childSKUs.saleVolumePrices,childSKUs.listVolumePrices, childSKUs.dynamicPropertyMapLong", "key": "productData" } ] }
Each filter must have a key
(which is used to identify the filter), and either an include
array (equivalent to the fields
query parameter) an exclude
array (equivalent to the exclude
query parameter), or both.
You can view an individual filter using the getFilter
endpoint. For example:
GET /ccadmin/v1/responseFilters/productData HTTP/1.1
Authorization: Bearer <access_token>
Note that you should not modify or delete the default response filters, as they are used by widgets provided with Commerce Cloud, and these widgets may not work properly if the response filters are changed. For information about these response filters and how they are used by widgets, see the Filter REST Responses chapter of the Developing Widgets guide.
Create response filters
You can create your own response filters using the createFilter
endpoint. For example, the following call creates a new response filter named productLabels
:
POST /ccadmin/v1/responseFilters HTTP/1.1 Authorization: Bearer<access_token>
{ "key": "productLabels", "include": "items.id,items.displayName,items.description" }
The following call uses the productLabels
filter to restrict the set of properties returned for products:
GET /ccadmin/v1/products?filterKey=productLabels HTTP/1.1
Authorization: Bearer <access_token>
The following shows a portion of the response:
"items": [ { "displayName": "A-Line Skirt", "description": "The simple perfect A line", "id": "xprod2535" }, { "displayName": "Acadia Wood Chair", "description": "Craftsman meets classic in this attractive wood chair", "id": "xprod2148" }, { "displayName": "Americana Nightstand", "description": "Classic American design", "id": "xprod2103" }, ... ] }
Modify response filters
You can use the updateFilter
endpoint to modify response filters. For example, the following call changes the set of properties returned by the productLabels
filter shown above:
PUT /ccadmin/v1/responseFilters/productLabels HTTP/1.1 Authorization: Bearer<access_token>
{ "include": "items.displayName,items.description,items.listPrice" }
Note that when you modify a response filter, the changes to the filter do not take effect until your JSON cache is cleared. This cache is cleared each time you publish changes on your Commerce Cloud instance. Changes to response filters themselves do not require publishing, so to force the cache to be cleared, you need to modify a publishable asset (such as an item in the product catalog) and then invoke publishing.
Delete response filters
You can use the deleteFilter
endpoint to delete a response filter. For example:
DELETE /ccadmin/v1/responseFilters/productLabels HTTP/1.1
Authorization: Bearer <access_token>