Skip to content

Configuring Pages

The Pages configuration API allows you to programmatically manage settings for Hello Retail Pages. This API provides an alternative to configuring pages through the my.helloretail.com.

Each page is identified by a unique page key, and every modification creates a new version with its own ID.

To use the endpoint, you need to know your company ID, website UUID, and have an API key. Log in to your account on https://my.helloretail.com/ and follow these instructions on how to find them.

Important Concepts

  • Page Key: A unique identifier for each page
  • Version ID: Each modification creates a new version with a unique ID
  • Page State: Pages must be in "LIVE" state for changes to be visible on your site
  • Optimistic Locking: Updates can only be made to the latest version to prevent conflicting changes. Changes to other versions will fail.

Endpoints

GET Fetch latest page configuration

Request Method: GET

Endpoint: https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/latest/{pageKey}?apiKey={apiKey}

Parameters

Path
Name Type Description
companyId String Your company ID.
websiteUuid String UUID of the website.
pageKey String The unique identifier for the page.
Query
Name Type Description
apiKey String A valid API key. It can be created on your Hello Retail dashboard.

Example JavaScript request

fetch(`https://core.helloretail.com/api/companies/${companyId}/websites/${websiteUuid}/pages/latest/${pageKey}?apiKey=${apiKey}`, {
    method: 'GET',
    credentials: 'include',
    headers: {
        'Content-Type': 'application/json'
    },
}).then((res) => {
    return res.json();
}).then((data) => {
    console.log(data)
});

Responses

200 OK        Page Configuration Data 
{
    "data": {
        "id": "123",
        "type": "page",
        "attributes": {
            "id": "123",
            "key": "women-shoes",
            "website_id": "4cc49be5-1111-2222-3333-d562511a66d3",
            "page_design_id": "design-001",
            "timestamp": "2024-01-15T14:45:00Z",
            "modified_by": "user@example.com",
            "name": "Women's Shoes",
            "archived": false,
            "superseded": false,
            "state": "LIVE",
            "ga_events_enabled": true,
            "ga_click_event_category": "product-click",
            "ga_click_event_action": "click",
            "ga_click_event_label": "women-shoes",
            "ga_view_event_category": "page-view",
            "ga_view_event_action": "view",
            "ga_view_event_label": "women-shoes",
            "show_out_of_stock_products": false,
            "filtered_by_grouping_key": true,
            "product_filters": [
                {
                    "field": "categories",
                    "values": ["Women", "Shoes"]
                }
            ],
            "product_score_boost": 1.0,
            "product_boosts": [
                {
                    "field": "brand",
                    "value": "Nike",
                    "boost": 2.0
                }
            ],
            "personalized_boosts": [
                {
                    "field": "product.pi.budgetZone",
                    "boost": 1
                }
            ],
            "url_overrides": [
                {
                    "url": "/women/shoes/special-collection",
                    "fixedProducts": [],
                    "productBoosts": [
                        {
                            "field": "collection",
                            "value": "special",
                            "boost": 3.0
                        }
                    ],
                    "showFilteredProducts": true,
                    "productScoreBoost": 1.5
                }
            ]
        }
    }
}
PATCH Update page configuration

Updates specific fields of a page configuration. Only the fields you send will be updated. Complex fields like "personalized_boosts" are considered single fields, so the entire list of wanted boosts needs to be included when updating.

Important: The page must be set to "LIVE" state for changes to be visible on your site. Updates to a page ID that is no longer the latest version will fail to prevent conflicting changes.

Request Method: PATCH

Endpoint: https://core.helloretail.com/api/companies/{companyId}/websites/{websiteUuid}/pages/{versionId}?apiKey={apiKey}

Parameters

Path
Name Type Description
companyId String Your company ID.
websiteUuid String UUID of the website.
versionId String The version ID of the page to update (obtained from GET request).
Query
Name Type Description
apiKey String A valid API key. It can be created on your Hello Retail dashboard.
Body
Name Type Description
request body JSON The page configuration data as JSON. See the example below.

Example JavaScript request

fetch(`https://core.helloretail.com/api/companies/${companyId}/websites/${websiteUuid}/pages/${versionId}?apiKey=${apiKey}`, {
    method: 'PATCH',
    credentials: 'include',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        data: {
            type: "page",
            attributes: {
                state: "LIVE",
                personalized_boosts: [
                    {
                        field: "product.pi.budgetZone",
                        boost: 2
                    },
                    {
                        field: "product.pi.productCluster",
                        boost: 4
                    }
                ]
            }
        }
    })
}).then((res) => {
    return res.json();
}).then((data) => {
    console.log(data)
});

Responses

200 OK        Updated Page Configuration

Returns the complete updated page configuration with all fields: 

{
    "data": {
        "id": "124",
        "type": "page",
        "attributes": {
            "id": "124",
            "key": "women-shoes",
            "website_id": "4cc49be5-1111-2222-3333-d562511a66d3",
            "page_design_id": "design-001",
            "timestamp": "2024-01-15T15:00:00Z",
            "modified_by": "api-user@example.com",
            "name": "Women's Shoes",
            "archived": false,
            "superseded": false,
            "state": "LIVE",
            "ga_events_enabled": true,
            "ga_click_event_category": "product-click",
            "ga_click_event_action": "click",
            "ga_click_event_label": "women-shoes",
            "ga_view_event_category": "page-view",
            "ga_view_event_action": "view",
            "ga_view_event_label": "women-shoes",
            "show_out_of_stock_products": false,
            "filtered_by_grouping_key": true,
            "product_filters": [
                {
                    "field": "categories",
                    "values": ["Women", "Shoes"]
                }
            ],
            "product_score_boost": 1.0,
            "product_boosts": [
                {
                    "field": "brand",
                    "value": "Nike",
                    "boost": 2.0
                }
            ],
            "personalized_boosts": [
                {
                    "field": "product.pi.budgetZone",
                    "boost": 2
                },
                {
                    "field": "product.pi.productCluster",
                    "boost": 4
                }
            ],
            "url_overrides": []
        }
    }
}

409 Conflict        Version Conflict Error

This error occurs when you try to update a page version that is no longer the latest. This prevents conflicting changes when multiple users or systems are updating the same page.

{
    "errors": [
        {
            "status": "409",
            "title": "Version Conflict",
            "detail": "The page version 123 is not the latest version. Please fetch the latest version and retry your update."
        }
    ]
}

Page Object Structure

The page object contains all configuration fields for a Hello Retail page. Below is a comprehensive list of all fields available in the page object:

Core Fields (Read-only)

These fields are managed by the system and cannot be updated via the API:

Field Type Description
id String The version ID of this page configuration
key String The unique page key identifier
website_id String The UUID of the website this page belongs to
type String Page type (fixed as "CATEGORY")
timestamp String ISO 8601 timestamp of when this version was created
modified_by String Email or identifier of who made the last modification
archived Boolean Whether the page is archived
superseded Boolean Whether this version has been superseded by a newer version

Updatable Fields

These fields can be modified via the PATCH endpoint:

Basic Configuration

Field Type Description
name String Display name of the page
state String Page state: "LIVE", "DRAFT", or "ARCHIVED"
page_design_id String The ID of the design template used
show_out_of_stock_products Boolean Whether to display products that are out of stock
filtered_by_grouping_key Boolean Whether products are filtered by grouping key

Google Analytics Configuration

Field Type Description
ga_events_enabled Boolean Whether Google Analytics events are enabled
ga_click_event_category String GA category for product click events
ga_click_event_action String GA action for product click events
ga_click_event_label String GA label for product click events
ga_view_event_category String GA category for page view events
ga_view_event_action String GA action for page view events
ga_view_event_label String GA label for page view events

Product Filtering and Boosting

Field Type Description
product_filters Array List of filters to apply to products
product_score_boost Number Global boost factor for all products (default: 1.0)
product_boosts Array Static boosts for specific product attributes
personalized_boosts Array Dynamic boosts based on user behavior and Product Intelligence

URL Overrides

Field Type Description
url_overrides Array Special configurations for specific URL patterns

Complex Field Structures

Product Filters

{
    "field": "categories",
    "values": ["Women", "Shoes"]
}

Product Boosts

{
    "field": "brand",
    "value": "Nike",
    "boost": 2.0
}

Personalized Boosts

{
    "field": "product.pi.budgetZone",
    "boost": 1.5
}

URL Overrides

{
    "url": "/women/shoes/special-collection",
    "fixedProducts": [],
    "productBoosts": [
        {
            "field": "collection",
            "value": "special",
            "boost": 3.0
        }
    ],
    "showFilteredProducts": true,
    "productScoreBoost": 1.5
}

Page States

State Description
LIVE Page is active and visible on your website
DRAFT Page is in draft mode and not visible to visitors
ARCHIVED Page is archived and not active

Example Workflow

Here's a complete example of updating various page configuration fields:

// Step 1: Fetch the latest page version
const getLatestPage = async (companyId, websiteUuid, pageKey, apiKey) => {
    const response = await fetch(
        `https://core.helloretail.com/api/companies/${companyId}/websites/${websiteUuid}/pages/latest/${pageKey}?apiKey=${apiKey}`,
        {
            method: 'GET',
            headers: { 'Content-Type': 'application/json' }
        }
    );
    return response.json();
};

// Step 2: Update the page configuration
const updatePage = async (companyId, websiteUuid, versionId, apiKey, updates) => {
    const response = await fetch(
        `https://core.helloretail.com/api/companies/${companyId}/websites/${websiteUuid}/pages/${versionId}?apiKey=${apiKey}`,
        {
            method: 'PATCH',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify({
                data: {
                    type: "page",
                    attributes: updates
                }
            })
        }
    );
    return response.json();
};

// Example 1: Update personalized boosts
const updatePageBoosts = async () => {
    try {
        // Get latest version
        const latestPage = await getLatestPage(companyId, websiteUuid, 'women-shoes', apiKey);
        const versionId = latestPage.data.id;

        // Update with new boosts
        const updatedPage = await updatePage(companyId, websiteUuid, versionId, apiKey, {
            state: "LIVE",
            personalized_boosts: [
                { field: "product.pi.budgetZone", boost: 3 },
                { field: "product.pi.productCluster", boost: 2 }
            ]
        });

        console.log('Page updated successfully:', updatedPage);
    } catch (error) {
        console.error('Error updating page:', error);
    }
};