Browse API: Browse Category Pages
This guide details the use of the Browse API for fetching products within a specific category, enabling the application of filters, sorting, and pagination to merchandised category pages.
Authorization
Token-based authentication is required for making requests to the Browse API. Include the X-Storefront-Access-Token
header with your API token.
Headers
Include these headers in your request:
X-Storefront-Access-Token: {token}
Content-Type: application/json
Accept: application/json
Path Parameters
collectionHandle
(string, required): The handle for the collection you’re browsing.
Body Parameters
filter_group
(object): A group of (filter conditions)[/engine/filtering] using various operators.pagination
(object): Specifies the page number and limit for pagination.sort_order_code
(string): The sort order for the results.facets
(array of strings): List of facets to include in the response.retrieveFacetCount
(boolean): If the count of each facet value should be calculated.identity
(object): Information used to current identify the customer/session.context
(object): Anonymous contextual information of the session/customer.attributes
(array of strings): Additional attributes to include in the response.
Making a Request
Here’s how to make a POST request to the Browse API:
curl -X POST 'https://app.uselayers.com/api/storefront/v1/browse/{collectionHandle}' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'X-Storefront-Access-Token: {YOUR_LAYERS_TOKEN}' \
-d '{
"filter_group": {
"conditional": "AND",
"expressions": [
{
"property": "product_type",
"operator": "eq",
"values": "shirt"
},
{
"filter_group": {
"conditional": "OR",
"expressions": [
{
"property": "id",
"operator": "exists",
"values": [1, 2, 3]
}
]
}
}
]
},
"pagination": {
"page": 1,
"limit": 20
},
"sort_order_code": "price_low_to_high",
"facets": ["vendor"],
"userToken": "user_token_string",
"attributes": ["title", "tags"]
}'
Response Structure
The API response will include an array of product objects, total results, pagination details, and optionally, facets. Here’s a snippet of the response:
{
"results": [
{
"id": 44370,
"title": "Supreme Pouch",
"body_html": "<p>Featuring iconic Supreme branding...</p>",
"vendor": "SUPREME",
...
},
...
],
"totalResults": 1000,
"page": 1,
"totalPages": 50,
"facets": {
"vendor": {
"ADIDAS": 30,
"JORDAN": 336,
...
}
},
...
}
Conclusion
With the Browse API, you can effectively manage and display merchandised category pages, providing a dynamic and responsive user experience. Customize your requests to sort, filter, and paginate as needed to suit your storefront’s design and performance requirements.
Was this page helpful?