Skip to content

Conversion tracking

The data provided in conversion tracking is used to provide better personalization as well as providing data for sales performance analyitcs accessible on my.helloretail.com.

Conversions should be tracked immediately when they occur on the webshop. This is typically implemented using the javascript SDK but can also be implemented using the REST API. The tracked cart is associated with the visitors trackingUserId.

We have information about how to configure conversion tracking for various platforms in on our support pages.

Beyond conversion tracking it is also often a usefull to provide Hello Retail with an order feed. This makes it possible to import historic orders and import orders from other sales channels.

Conversion tracking using the SDK

When a conversion occurs you can track it by calling the trackConversion method. The method accepts two arguments:

Arguments

Argument Type Description
data Conversion object See specification of the conversion object below.
callback() function Will be called without any arguments when conversion tracking is finished. Optional.

Properties of the Conversion object

Property Type Description
total Number The total value of the conversion.
orderNumber String Unique order number for this conversion. Must be identical to the order number provided in any order feeds
email String Email addres of the customer making the order
customerId String If you have an internal ID for the customer you can optionally include it here. You might have this if the customer is logged in
urls String[] A list of canonical urls of the products in the order. They are used to identify the products in the order, they must match the urls of the products given to Hello Retail in the product feed or when using the product REST API. You must provide either urls or productNumbers.
productNumbers String[] A list of unique product numbers of the products in the order. They are used to identify the products in the order, they must match the product numbers of the products given to Hello Retail in the product feed or when using the product REST API. You must provide either urls or productNumbers.

Example of tracking using product urls

hrq = window.hrq || [];
hrq.push([
    "trackConversion",
    {
        total: 499.32,
        orderNumber: '110-2347',
        email: 'customer@example.com',
        customerId: '53967',
        urls: [
            'http://example.com/shop/product-1234',
            'http://examplec.mo/shop/product-4567'
        ]
    }, 
    function() {
        console.log('Conversion has been tracked');
    }
]);

Example of tracking using product numbers

hrq = window.hrq || [];
hrq.push([
    "trackConversion",
    {
        total: 499.32,
        orderNumber: '110-2347',
        email: 'customer@example.com',
        customerId: '53967',
        productNumbers: [
            'p-1234',
            'p-4567'
        ]
    }, 
    function() {
        console.log('Conversion has been tracked');
    }
]);

Conversion tracking using the REST API

The Hello Retail SDK uses a REST API endpoint to track the conversion. This API can also be used directly.

Request

The endpoint is available at https://core.helloretail.com/serve/collect/conversion. You use it by sending a HTTP POST request with a JSON body. The content type must be application/json or text/plain 1.

The JSON body must match the Conversion Object documented for the javascript SDK above, but it must also contain the trackingUserId of the visitor and whe websiteUuid of the webshop.

Example of the structure the JSON body must have:

{
    "trackingUserId": "{tracking user id}",
    "websiteUuid": "{website uuid}",
    "total": 499.32,
    "orderNumber": "123-4567",
    "email": "customer@example.com",
    "customerId": "123456",
    "productNumbers": [
        "p-1234",
        "p-4567"
    ]
}

More information about each part of the JSON body

Property Type Description
trackingUserId String Tracking user id that has been generated by Hello Retail. You can read more about the tracking user here
websiteUuid String The id identifying the website in Hello Retail. This can be found on my.helloretail.com
email String Email addres of the customer making the order
customerId String If you have an internal ID for the customer you can optionally include it here. You might have this if the customer is logged in
urls String[] A list of canonical urls of the products in the order. They are used to identify the products in the order, they must match the urls of the products given to Hello Retail in the product feed or when using the product REST API. You must provide either urls or productNumbers.
productNumbers String[] A list of unique product numbers of the products in the order. They are used to identify the products in the order, they must match the product numbers of the products given to Hello Retail in the product feed or when using the product REST API. You must provide either urls or productNumbers.

Response

The response will indicate if the tracking succeeded. A success response will have the 200 response code. The body of the response will look like this:

{
    "success": true,
    "message": "Conversion tracked"
}

If the tracking fails because of invalid input the response will have the 400 response code. An example could be not supplying the websiteUuid or supplying a websiteUuid that does not match a website. This will result in the following response:

{
    "success": false,
    "message": "Website not found"
}

If the tracking fails for other reasons it will fail with the 500 response code. If you experience this please contact Hello Retail support.

  1. The reason for supporting text/plain is to allow requests to this endpoint, made from the browser, to be categorized as simple thereby avoiding CORS preflight requests. You can read more here https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests ↩