Response filters

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:

{
  "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, 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 Filter REST Responses.

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