Browse API: Browse 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.