Introduction to the Hello Retail REST API and JavaScript SDK
Hello Retail provides a REST API that allows using the features and tracking programatically. The helloretail.js script provides an SDK that is an easy-to-use way of using the API from javascript directly on the website.
The APIs and SDK methods are documented in the sections for each feature. Below you will find an overview of the available SDK methods
The JSON Product Object
The products in your product catalog are central to your shop and your Hello Retail configuration. Therefore, the product object is available in the response to many REST and SDK responses. The product objects reflect the data in your product catalog. The catalog is synchronized to Hello Retail through product feeds. The product object contains the following properties.
| Field | Descripton |
|---|---|
| title | Product title |
| productNumber | Product number |
| imgUrl | URL of the primary product image |
| url | URL of the product + a fragment containing the trackingCode. If helloretail.js is configured on a site and this fragment appears in the url, helloretail.js will automatically track a click on this product in a hello retail solution. Example: https://shop.example.com/products/12/#aw_source=xx-asdasd-asdasd |
| originalUrl | URL of the product |
| trackingCode | Tracking code that can be sent to the /collect/click endpoint to track a click on this product in a hello retail solution |
| retailMediaCampaignId | If the product is in this position because of a Retail Media campaign this field will contain the ID of the associated campaign. This is useful for adding custom design elements, like for instance a "sponsored" label |
| variantProductNumbers | If multiple products have the same grouping key they will all get each others product numbers combined into this list. It is also possible to manually set the numbers in this field from the product feed |
| ean | EAN number of the product |
| brand | Brand of the product |
| inStock | Boolean value indicating if the product is in stock or not |
| price | Price of the product |
| priceExVat | Price without vat of the product |
| oldPrice | Previous price of the product |
| oldPriceExVat | Previous price without vat of the product |
| currency | Currency configured on the website |
| isOnSale | Boolean indicating if the price is lower than the oldPrice |
| description | Description of the product |
| keywords | Keywords of the product |
| hierarchies | A list of lists where each inner list represents a hierarchy for the product (also referred to as a category or breadcrumb) |
| extraData | A dictionary of custom string attributes. Can be referred to as {{ product.extraData.x }} in the liquid templates. Where x is the name of the custom attribute |
| extraDataNumber | A dictionary of custom number attributes. Can be referred to as {{ product.extraDataNumber.x }} in the liquid templates. Where x is the name of the custom attribute |
| extraDataList | A dictionary of custom string list attributes. Can be referred to as {{ product.extraDataList.x }} in the liquid templates. Where x is the name of the custom attribute |
SDK methods
| Command | Descripton | Example |
|---|---|---|
| getCustomerBias | Gets customer bias | Customer bias |
| getTrackingOptOut | Opts the user out of tracking | Opt in and out of Tracking |
| getTrackingUserId | Get's the user id for tracking | Getting the trackingUserId |
| loadPage | Loads a particular page | Loading page content using JavaScript |
| loadRecom | Loads the recommendations | Recoms using Javascript SDK |
| reload | Reloads the current page | Reloading for view tracking and initialization |
| search | Fetches a search resultset | Sending search requests |
| setCart | Setting and clearing the cart | Cart tracking using the SDK |
| setCustomerEmail | Sets the user email | Register email on tracking user |
| setCustomerId | Sets a custom user id | Set a custom id on your customer |
| setTrackingOptOut | Updates the user tracking profile | Opt-in and -out of tracking |
| trackClick | Tracks clicks on Search, Pages and Recommendations | Click tracking |
| trackConversion | Tracks a user purchase/conversion | Conversion tracking |
| trackPageView | Tracks a user page view | View tracking |
| triggeredEmailSubscribe | Subscribes user to triggered emails | Subscribe using the SDK |