REST-API

The Pages REST API consists of a single endpoint to fetch a page.

Click on the arrow to see the details of the parameters:

POST Fetch content for a page identified by key

Fetches content for a page identified by key. The request must be sent as a POST request with the content-type application/json. The request body is a JSON object with the properties described below.

Request Method: POST

Endpoint: https://core.helloretail.com/serve/pages/{key}

Parameters

Path

Name	Type	Description
key	String (required)	The key of the page to load.

Body

Name	Type	Description
url	String (required)	The url of the page. Used for analytics.
id	Integer	ID of a version of a page. Only needed if you want to fetch the Draft version of a page.
format	String	Specify the format in which the API will return the results. HTML and JSON are accepted values, default value is HTML.
fields	String[]	Product fields to return. By default, the system will return all the fields of a product. If you want to use product data from your own database to render the products, and just need a way of knowing what products to include on the page, then you can pass "productNumber", and we will only return the productNumber for each product. You can then use the returned value to find the producs in your own database.
params	Object (Required)	Parameters that are passed as input to the product filters.
trackingUserId	String (required)	Hello Retail ID of the user visiting your site. This is used to apply personalization and for tracking purposes. You can get this ID server side by getting the value of the cookie named hello_retail_id.
firstLoad	Boolean (Required)	Indicates if this is the first render of the page. This allows the template to only return some content on the first load. Views of the page will only be tracked if firstLoad is true.
products.start	Integer (Required)	Starting point when fetching products for the page.
products.count	Integer (Required)	Number of products to return from the starting point.
products.filters	String[]	List of filters to filter products by.
products.sorting	STring[]	List sorting options.

Example cURL Request

curl --location --request POST 'https://core.helloretail.com/serve/pages/62b434f72e59c03e6cd41206' \
     --header 'Content-Type: application/json' \
     --data-raw '{
            "id": 2,
            "url": "https://example-shoe-shop-url.com/women/shoes",
            "layout": true,
            "firstLoad": true,
            "trackingUserId": "62a0317d17698aa57d369db9",
            "format": "json",
            "params": {"filters":{"hierarchies": ["Women", "Shoes"]}},
            "products": {
                "start": 0,
                "count": 50,
                "fields": ["id", "title", "price"],
                "filters": [
                    "brand:New\\ Balance",
                ],
                "sorting": [
                    "title desc"
                ]
            }
        }

Example JavaScript request

fetch('https://core.helloretail.com/serve/pages/62b434f72e59c03e6cd41206', {
"method": 'POST',
"mode": 'cors',
"credentials": 'include',
"headers": {
    'Content-Type': 'application/json'
},
"body": JSON.stringify({
    "id": 2,
    "url": 'https://example-shoe-shop-url.com/women/shoes',
    "layout": true,
    "firstLoad": true,
    "trackingUserId": '62a0317d17698aa57d369db9',
    "format": 'json',
    "params": {
        "filters": '{"hierarchies":["Women", "Shoes"]}'
    },
    "products": {
        "start": 0,
        "count": 50,
        "fields": ["id", "title", "price"],
        "filters": [
            "brand:New\\ Balance",
        ],
        "sorting": [
            "title desc"
        ],
    },
})
}).then((res) => {
    return res.json();
}).then((data) => {
    console.log(data)
});

• Note how spaces should be escaped (see brand filter) with two backslash space: "\ ". The filter requires the space to be escaped with a slash, and then the slash has to be escaped with another slash because it is a javascript string. Normally you would get the possible filter values in the response from the server, where they would already be escaped correctly.

Responses

200 OK        HTML Response Object

{
    success: true,
    layout: "<div>some html from the layout<div class=\"helloretail-pages-products\"></div> some more html</div>", // Layout from the beefree editor. Not included for category pages
    firstLoad: true,
    products: {
        start: 0,
        count: 50,
        total: 500,
        html: "<div>Products rendered using the design selected for the page</div>",
        javascript: "/* javascript from the design selected for the page */",
        style: "/* css from the design selected for the page */"
    }
}

200 OK        JSON Response Object

{
    success: true,
    layout: "<div>some html from the layout<div class=\"helloretail-pages-products\"></div> some more html</div>", // Layout from the beefree editor. Not included for category pages
    firstLoad: true,
    products: {
        start: 0,
        count: 50,
        total: 500,
        html: "",
        result: [
            {
                "title": "abc",
                "url": "url/url.com",
                "imgUrl": "imgurl/url.com",
                "currency": "DKK",
                "priceLowered": true,
                "description": "sample description",
                "keywords": "ab, gh, dd",
                "inStock": true,
                "productNumber": "product1234",
                "variantProductNumbers": [],
                "price": 233.44,
                "previousPrice": 500.23,
                "score": 7.0
            },
            ...
        ],
        javascript: "/* javascript from the design selected for the page */",
        style: "/* css from the design selected for the page */"
    }
}