Skip to main content

Collections

Collections are a powerful tool to create groups of items based on dynamic rules. For instance, one can define the Cyber Monday collection as "the set of all items from the Electronics category which cost less than $200, as well as all laptops that cost less than $800".

Any combination of facets (uploaded through the Items API) and group ids can be used in the filter_expression that defines a collection.

Items can also be manually added to a collection with the items field. (See the section on adding items to a collection manually)

To serve production end-user collection requests, use the browse endpoint by specifying a collection's id /browse/collection_id/<collection_id>.

Features​

  • Fast: A new collection can be retrieved by end users in less than 2 minutes after creation. Updates to collection rules are also applied in under 2 minutes.
  • Dynamic: Collections are dynamic in nature. When you upload a new item, you don't have to specify which collection it belongs to: It will be automatically included in all collections whose criteria it matches.
  • Personalized: New users that view a collection see the most popular items in the collection first. Returning users see items ranked based on those items most similar to their purchase and view history.
  • Searchandizable: Just as search queries can have powerful slotting or boosting rules applied, collections support powerful merchant controls over item ranking.
  • Expressive: Collections are defined by a very powerful filtering language that allows combining filters in any way you see fit. (See filter expression below)

Create collection​

To create a collection, use the POST method.

Create a collection
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"id": "my-id", "display_name": "My Collection", "filter_expression": {"name": "Type", "value": "Laptop"}, "data": {"foo": "bar"}}'
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]"
Response
{
  "id": "my-id",
  "created_at": "2019-04-12T18:15:30",
  "updated_at": null,
  "display_name": "My Collection",
  "filter_expression": { "name": "Type", "value": "Laptop" },
  "data": { "foo": "bar" }
}

HTTP request​

POST https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section that contains items in this collection

JSON Parameters​

AttributeTypeRequired?Description
idstringYesThe id that you want to use to refer to this collection
display_namestringYesA display name for this collection
filter_expressionobjectNoThe filter expression that defines this collection.
dataobjectNoJSON object with custom metadata attached with the collection. Defaults to null if not provided. *

Add items dynamically​

Items are added dynamically with logical operators composed of filters (facets and item groups) via the filter_expression.

  • A filter can be of the form {"name": "filter_name", "value": "filter_value"} to match a single filter value. If the name is group_id, the value is expected to be the ID of an item_group.
  • A filter can also be of the form {"name": "filter_name", "range": [min, max]} to match a range of values. For example {"name": "Price", "range": [50, 100]} matches all items that are priced between $50 & $100. If you want to create a range that has no upper bound, you can set the max value to the string "inf". Similarly, the string "-inf" as the min value would define a range without a lower bound.
  • A single filter (as defined above) is a valid filter_expression.
  • A filter_expression of the form {"and": [expr1, expr2, expr3, ...]} matches all items that match all of the expressions in the list (where expr1, expr2, expr3 are filter_expressions).
  • A filter_expression of the form {"or": [expr1, expr2, expr3]} matches all items that match any of the expressions in the list.
  • A filter_expression of the form {"not": expr} matches all items that do not match the expression expr.
  • filter_expressions may be nested (at most 5 levels).
  • filter_expressions may not contain more than 150 expr expressions (in total).
This could be a valid filter_expression for the 
{
  "or": [
    {
      "and": [
        {
          "name": "group_id",
          "value": "electronics-group-id"
        },
        {
          "name": "Price",
          "range": ["-inf", 200]
        }
      ]
    },
    {
      "and": [
        {
          "name": "Type",
          "value": "Laptop"
        },
        {
          "not": {
            "name": "Price",
            "range": [800, "inf"]
          }
        }
      ]
    }
  ]
}

Add items manually​

As discussed above, collections allow customers to create dynamic assortments of products based on rules using product facet and category (group) taxonomy. This allows dynamic product assortments for one-time uses like emails, as well longer-lived featured product listings to link from the homepage or elsewhere. One example is if a merchant wanted to show all McCormick's Farmstand brand Pet Food products that are Organic and between $10 an $20.

In addition to the dynamic rules, customers may also add items manually one-by-one to include products in the collection that may not correspond exactly to a set of product filters. One example is if there's a list of promotional products from a Brand partner.

Collections slotting in the searchandizing UI allows making these manual additions, and the items endpoint on a collections resource (documented here) allows this manual update from API.

Adding (or modifying) items added to a collection manually will require an index build, so changes go live in around 30 minutes or less depending on the size of the index. Plan your updates accordingly, especially when replacing conditions (which changes take effect in a couple of minutes) with items.

curl -X PUT -H "Content-Type: application/json" \
  -d '{"items": [{"id": "pug"}]}' \
  -u"[your token]:" "https://ac.cnstrc.com/v1/collections/dog-collection/items?key=[your API key]&section=[your section]"
Example request body
{
  "items": [
    {
      "id": "pug1"
    },
    {
      "id": "pug2"
    }
  ]
}
info

The above command returns a 200 Success response on success.

HTTP Request​

PUT https://ac.cnstrc.com/v1/collections/[collection_id]/items?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
collection_idstringYesThe id of the collection you would like to add items to.

JSON Parameters​

ParameterRequired?Description
itemsYesArray of the items (each with a required id field) you wish to manually add to the collection.

Remove manual items​

Items that have been added manually can be removed with the DELETE method.

curl -X DELETE -H "Content-Type: application/json" \
  -u"[your token]:" \
  "https://ac.cnstrc.com/v1/collections/dog-collection/items/labradoodle?key=[your API key]&section=[your section]"
info

The above command returns a 204 Success response on success.

HTTP Requests​

DELETE https://ac.cnstrc.com/v1/collections/[collection_id]/items/[item_id]?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
collection_idstringYesThe id of the collection you would like to remove items from.
item_idstringYesThe id of the item you wish to remove.

Retrieve all collections​

To retrieve all collections, use the GET method.

Get collections
curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:" \
  "https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]&sort_by=display_name&sort_order=ascending&page=1&num_results_per_page=20"
Response
{
  "collections": [
    {
      "id": "my-id",
      "created_at": "2019-04-12T18:15:30",
      "updated_at": null,
      "display_name": "My Collection",
      "filter_expression": { "name": "Type", "value": "Laptop" },
      "data": { "foo": "bar" }
    }
  ],
  "total_count": 1
}

HTTP request​

GET https://ac.cnstrc.com/v1/collections?key=[your API key]&section=[your section]&sort_by=display_name&sort_order=ascending&page=1&num_results_per_page=20

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section in which your collection is defined. Typically, this will be Products.
querystringNoSearch for collections with a matching id or display name
sort_bystringNoField name to sort results by. One of display_name, created_at, updated_at
sort_orderstringNoSort order of results sorted by sort_by field. One of ascending, descending. Defaults to ascending if not provided
num_results_per_pageintegerNoThe number of collections you want to retrieve
pageintegerNoThe page number (defaults to 1) Can't be used together with 'offset'
offsetintegerNoThe number of results to skip from the beginning. Can't be used together with 'page'

Retrieve a single collection​

To retrieve a single collection, use the GET method.

Get collection
curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"
Response
{
  "id": "my-id",
  "created_at": "2019-04-12T18:15:30",
  "updated_at": null,
  "display_name": "My Collection",
  "filter_expression": { "name": "Type", "value": "Laptop" },
  "data": { "foo": "bar" }
}

HTTP request​

GET https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section in which your collection is defined. Typically, this will be Products.

Retrieve collection items​

Intended use

The retrieve collection items endpoint allows developers to verify items added to a collection are returned as expected (without having to wait for an index rebuild) or to sync collection items with outside systems of record, such as an eCommerce platform. To simplify both of these activities, the retrieve collection items endpoint will return all items in the collection and is not capped at a maximum of 999 items.

Note: this endpoint is intended for backend development or integration purposes and is not supported for serving production end-user traffic.

To serve production end-user collection requests, use the browse endpoint by specifying a collection's id as so: /browse/collection_id/<collection_id>.

The browse endpoint provides several benefits:

  • Results will be personalized and ranked according to KPIs and user behavior.
  • Results will include item names, facets and other metadata (the development API documented here omits these).
  • The browse endpoint is architected for scalability and provides response time guarantees.

Request format

To retrieve collection items, use the GET method on the collection items resource.

Items added manually and dynamically can be retrieved together or separately by setting manual_items and dynamic_items flags with the request below:

curl -X GET \
  -H "Content-Type: application/json" \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/dog-collection/items?key=[your API key]&section=[your section]&filters[manual_items]=true&filters[dynamic_items]=false&page=1&num_results_per_page=3"

HTTP Request​

GET https://ac.cnstrc.com/v1/collections/[collection_id]/items?key=[your API key]&section=[your section]&filters[manual_items]=true&filters[dynamic_items]=true&page=1&num_results_per_page=3

Response format​

{
  "items": [
    {
      "id": "corgi",
      "type": "dynamic"
    },
    {
      "id": "dachshund",
      "type": "dynamic"
    },
    {
      "created_at": "2019-04-12T18:15:30",
      "updated_at": null,
      "id": "labradoodle",
      "type": "manual"
    }
  ],
  "total_count": 3
}

URL Parameters​

AttributeTypeRequired?Description
collection_idstringYesThe id of the collection from which you'd like to retrieve items.

Query Parameters​

AttributeTypeRequired?Description
keystringYesThe index you'd like to to retrieve results from.
sectionstringNoThe section in which your collection is defined. Typically, this will be Products, but the default section will be chosen if no value is provided.
filters[manual_items]booleanNoWhether to include manually added items in the response. Defaults to true.
filters[dynamic_items]booleanNoWhether to include dynamic items (matching collection.filter_expression) in the response. Defaults to false for backwards compatibility.
pageintegerNoPage number. Defaults to 1.
num_results_per_pageintegerNoNumber of items per page. Default value is 100.

Response format​

AttributeTypeDescription
idstringItem customer ID.
typestringDescribes the method of addition for the item - manual if it was manually added to the collection, dynamic if it matches collection.filter_expression.
created_atstringPresent only for manually added items. Time when the item was added to the collection. (ISO8601 format)
updated_atstringPresent only for manually added items. Time when the item-collection association was last updated (ISO8601 format)

Update a collection (completely)​

To update a collection completely (replace), the PUT method needs to be used.

Replace collection
curl -X PUT \
  -H "Content-Type: application/json" \
  -d '{"id": "new-id", "display_name": "New Collection Name", "filter_expression": {"name": "Type", "value": "New"}, "data": {"foo": "bar"}}' \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"
Response
{
  "id": "new-id",
  "created_at": "2019-04-12T18:15:30",
  "updated_at": "2019-04-13T19:15:30",
  "display_name": "New Collection Name",
  "filter_expression": { "name": "Type", "value": "New" },
  "data": { "foo": "bar" }
}

HTTP request​

PUT https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section in which your collection is defined. Typically, this will be Products.

JSON Parameters​

The JSON parameters are the same as those in the Create collection section

Update a collection (partially)​

To update a collection partially (change only some attributes) the PATCH method needs to be used.

Modify collection
curl -X PATCH \
  -H "Content-Type: application/json" \
  -d '{"display_name": "New Collection Name"}' \
  -u "[your token]:"
  "https://ac.cnstrc.com/v1/collections/my-id?key=[your API key]&section=[your section]"
Response
{
  "id": "my-id",
  "created_at": "2019-04-12T18:15:30",
  "updated_at": "2019-04-13T19:15:30",
  "display_name": "New Collection Name",
  "filter_expression": { "name": "Type", "value": "Laptop" },
  "data": null
}

HTTP request​

PATCH https://ac.cnstrc.com/v1/collections/<collection_id>?key=[your API key]&section=[your section]

URL Parameters​

AttributeTypeRequired?Description
sectionstringYesThe section in which your collection is defined. Typically, this will be Products.

JSON Parameters​

The JSON parameters can be any subset of those listed in the Create collection section

System Status​

To check the health of the system that serves /collections requests, you can issue a GET /status/product/collections, as shown below:

Check if the 'collections' system is healthy
curl -X GET "https://ac.cnstrc.com/status/product/collections"

A healthy system will reply with {"message": "OK"}