Miva merchant installation guide

updated 1 yr ago

To integrate Hello Retail with your Miva merchant web shop simply follow these few steps:

1. Insert the Hello Retail general script:

Log in to your Miva merchant backend, navigate to User interface -> CSS/Javascript Resources and then click the Javascript Resources tab. You should end up here:

Now click the blue Add Javascript Resource button in the top right corner to add a new resource to the list. Give it the code "hello-retail-general", select "inline script" in for the type and be sure to toggle both the global and active on.
Now hit the Save Changes button

Now you select the hello-retail-general resource by marking its checkbox.
A button containing three dots will appear in the top. Click it and select Edit Source.

A popup will open up and you will have to copy this snippet and paste it in the popup.

(function() {
    var aws = document.createElement('script');
    aws.type = 'text/javascript';
    if (typeof(aws.async) != 'undefined') { aws.async = true; }
    aws.src = 'https://helloretailcdn.com/helloretail.js';
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(aws, s);
})();
window.hrq = window.hrq || [];
hrq.push(['init', {}]);
hrq.push(['setCart', {
    total: '&mvt:global_minibasket:total',
    url: '&mvte:urls:BASK:auto_sep;Session_ID=&mvte:global:Basket:session_id',
    productNumbers: [<mvt:foreach iterator='item' array='global_minibasket:groups'>
        '&mvt:item:code',
    </mvt:foreach>]
}]);

Click Update / Save after you inserted the script.

Now Click the three dots button again and select Resource Groups.
A popup will open and you should toggle in the head_tag in the assigned column:

2. Insert the Hello Retail conversion script:

Just like we did for the Hello Retail general script, click the blue Add Javascript Resource button in the top right corner. This time we give it the code "hello-retail-conversion", select "inline script" as the type and make sure we toggle active on but global off.
Now hit the save button.

Next we select the Hello Retail conversion resource, click the three dots button and select Pages. A popup will open where you have to select the page where the script should be loaded.

Search for "INVC" to find the invoice template and toggle that on in the assigned column

Next we click the three dots button again, select Resource Groups and toggle on head_tag in the popup - just like we did for the Hello Retail general script.

Final step is to click the three dots button, select Edit Source and then paste this snippet in the popup window that shows:

hrq = window.hrq || [];
hrq.push(['trackConversion', {
    total: '&mvt:order:total',
    orderNumber: '&mvt:order:id',
    email: '&mvt:order:bill_email',
    productNumbers: [<mvt:foreach iterator='item' array='order:groups'>
        '&mvt:item:code',
    </mvt:foreach>]
}]);

Press Save / Update

3. Create API credentials:

Navigate to Settings -> User Management and then click the API Tokens tab.
Here you click the blue Add API Token in the top right corner.

Give it a name, add 0.0.0.0/0 to the Allowed IP Address(es) field and make sure you Generate and Copy the Endpoint URL, the Access Token and the Signature. These credentials are needed for Hello Retail, so have them handy.
Hit the Save button.

Now select the API Token we just created by clicking its checkbox, press the three dots button that appears and select Groups. A popup appears where you have to select the access rights for this API Token. Make sure you toggle both Order Processing & Fullfilment and Product Management ON

4. Create CSV feed for product discount prices and extra data:

Because the Miva merchant API in its current state doesn't support price groups, it is not possible to get the complete discounted price for products affected by price groups.
To get around this we need to create a supplementary csv feed.

This feed will also allow us to include custom fields that you find necessary for your Hello Retail integration to be complete.

Navigate to Marketing -> Feeds and click the blue Add Feed button:

A popup will appear like the one below. We suggest you just copy paste the settings and names from our example below. The setting Enable URI Access and the URI Access Key value along with settings related to email are not necessary. Make sure you remember to select Product in the template option in the bottom.

After you press the Add button you can open the feed again and a link to Edit Template will appear - click on it.

Now You should be on the Edit Page for the feed we just created.
Click the Items tab and make sure the modules Template Based Feed and Standard Product Fields are toggled on. If you want to add Custom fields you should toggle that one as well.

Go back to the Page tab and scroll down until you see the Template Based Feed section. Make sure you set the Mode = Product, Load = Active, Encoding = CSV, Predict Product Discounts = checked.
For the Product fields you only need Code and Price.
For the Custom fields you don't need any, but you can add fields you might find useful for your Hello Retail setup.

5. Create scheduled task to update the CSV feed:

For this feed to stay updated, you need top create a scheduled task that will do this automatically for you.

Navigate to Settings -> Store Settings -> Scheduled Tasks tab and then click the blue Create New Scheduled Task button

A popup window will appear as the one below. We recommend it run every 30 minutes, but if you rarely do price rule changes you can set it to run less often.

The Next Run field will fill itself.

Click the LOOK UP button to select the Hello Retail feed we just created (See image below) and click Add

Note that if your product feeds at Hello Retail are blocked, it might be due to our servers being blocked by Miva. If this happens, then contact Miva's support and ask them to unblock the following IP address: 34.245.105.75.

Configure Webshop

After the installation setup of your platform and the onboarding flow, make sure to have your webshop configured. Read this guide here on how to do so:

Configure Webshop