Recommendation API – Solution architecture perspective for Microsoft Dynamics customers

Read this post to get an overview of this API and to get better understanding of how to build a solution using this service. For details about the service itself read the technical documentation.



Who uses the recommendations API?
Recommendations API is popular with Microsoft Dynamics customers, particularly in distribution and retail space. The service is live at JJ Foods (UK) since Nov 2014 and at Bunzl Group (DE, NL) since Feb 2016. Many other Dynamics AX & NAV customers are trying out the service with their data. There are many other companies that do not use Dynamics AX but use this service - like a TV channel that recommends programs to watch to its customers, a computer hardware supplier that recommends technology products to its customers, a telecom operator who recommends more relevant services to its customers, Microsoft X-Box and others. The service itself is independent of both the e-commerce platform and the ERP backend. So, even though we talk mostly about Dynamics AX in this post, a basic integration to other systems is equally simple and straightforward.
Current service has been proven to run on e-commerce portal, in a call-center scenario as well as in a mobile app. Recommendations API is the first in a line of Cortana Intelligence Suite based APIs available through Azure marketplace that we will provide deeper integrations into Dynamics AX and Dynamics CRM. It is fairly easy to get the basic service implemented into either your e-commerce portal or into Dynamics AX client. Read below and chose from one of the implementation approaches that best supports your environment. Basic approach allows you to have something simple ready and providing value on your online shop in less than a week. Intermediate approach ensures you have all consumption experiences modeled (online shop, AX, NAV, CRM, mobile app, E-POS, M-POS etc.) and all your data management requirements automated so the service runs without manual intervention. Advanced approach ensures you can handle separate models for multiple sites, environments and catalogues in a robust and automated fashion and also have deep integration into your groups’ business processes.

Why should I use recommendation API?

If you sell products and services online or through a call-center, recommendations API will allow you to get a lift of 1-2% from the get-go. The model will improve as it learns more. With a simple out-of-the box service that is easy to integrate to any systems you have, that requires very little maintenance and that is flexible, learns and changes with your business you can derive additional revenue from the day you start using the service with a payback period of few hours every month.

In B2B distribution scenarios, over a period of time customers settle into buying just a limited set of items from you while preferring other suppliers for other items. We all need some stability so even when you change your catalog, offer new trade discounts, even when customers' business changes, buyers get replaced - it is only rare that customers review the items they are buying from you. In such an environment if with little help you can nudge the customer a bit by exposing the 'hidden' products - products they didn't realize you carry, you can secure a tremendous lift for yourself.

In both distribution and retail scenarios it is simply not possible for any one person to know all the possible combinations of products that are bought together and it is impractical to use your transactional application to set the recommendations up per product, per group of products or per customer-product combination. Even though there is capability in Dynamics AX2012 call-center module to setup the cross-sell and up-sell rules but we have rarely found customers using this capability. Because it requires huge investment of time to setup and to maintain. This is exactly the point where recommendation API that lives off your transactional system and works by itself with little investment from your side becomes very useful. Unlike some other machine learning based services there is limited downside if you are not happy with the products being recommended. You can just turn it off and cancel your subscription without material harm to your business.

What is recommendation API?


The Recommendations API built with Microsoft Azure Machine Learning helps your customer discover items in your catalog. Customer activity in your digital store is used to recommend items and to improve conversion in your digital store. The recommendation engine may be trained by uploading data about past customer activity or by collecting data directly from your digital store. When the customer returns to your store you will be able to feature recommended items from your catalog that may increase your conversion rate.

Microsoft Azure Machine Learning's Recommendations supports 3 common scenarios:

  1. Frequently bought together (also called FBT)
  2. Item to item recommendations (also called I2I)
  3. Customer to Item recommendations (also called user-to-item or U2I)

In case of FBT, recommendation engine will recommend items that are likely to be purchased together in the same transaction with a particular item. For instance a customer who bought a mouse is also very likely to buy a keyboard.

In case of I2I, recommendation engine will recommend 'customers who bought/clicked this item also bought/clicked on following other items' type recommendations. For instance a customer browsing and clicking for a bottle of Chardonnay will be offered other similar wine choices.

In case of U2I, given customer's prior activity, it is possible to recommend items that the customers may be interested in. For instance, given all movies watched by a customers, it is possible to recommend additional content that may be of interest to the customer.

There are three main things to consider when architecting a solution using recommendations API

  1. Data management
  2. Model management
  3. API consumption experience (Integration to business process)

This API has been built by same team who built this other very popular service.

See how to start using the recommendation API with help of the video

Data management

Two data files are required to train the Azure ML model that gets deployed in the background when you use this service. These are (1) catalogue data that describes basic product characteristics and (2) sales data that model uses to determine the nature of each basket. You will obviously need to supply this data to the model. More data you provide better results you will get. So, a lot of data needs to be sent. And sent regularly. You could choose to send catalogue data weekly, monthly or at another interval and you could choose to send sales data every night or at another interval. You can choose to do this manually or you can automate it. You can also set it up so model collects the clickstream data from your digital store itself. You could segregate models per company, per catalogue if that is a must depending on your environment or you could put all together for one model. There are other choices to be made here as well which will become more obvious after you have reached this point in your investigation.

Model management
We believe for all relatively small to medium size implementations, one model will be sufficient. But you could have scenarios like multiple segregated companies that could require you to have multiple models. As you read the API documentation you will realize there are APIs that you can call to interact with the model and to manage it to some extent. However most of this will require a higher level of proficiency with using the service and you may still find that you need to write some custom scripts to really interact with models and manage them effectively. We bucket such requirements under advanced scenarios. When you reach this stage in your investigation, feel free to contact us or your partner and we will provide the required support.

API consumption experience
The recommendations API documentation covers in good detail how to call the service from within your application (online shop). In next few months, we will provide code and patterns on how to do this from within Dynamics AX. Several Microsoft Dynamics partners are also developing their own patterns for consumption experiences within Dynamics AX & NAV. Check with your partner if they already have some collateral to assist you. We will provide patterns on how to display recommendations (1) inside sales order, (2) on E-POS device and (3) on M-POS device. The recommendations API also allows you to setup rules like whitelists (to always display some products in recommendations), blacklists (to never display these products in recommendations) and others. You could make use of these capabilities to enhance the consumption experience. You could also work with your partner to provide more advanced and deeper integration to your back-end application.

What are some common scenarios where customers can use this service?


  1. Offer recommendations when shoppers are shopping on an online shop/digital store
  2. Offer recommendations when call-center agents are taking a sales call
  3. Offer & print recommended items on invoice generated at POS for future use
  4. Offer recommendations when customers place orders using a self-service mobile app
  5. Offer recommendations in a mobile app when a client interacts with an in-store professional

Where can I get the recommendation API?

It’s available on azure marketplace here

How should I use the recommendation API?

Basic Approach
Sign-up for the service here, purchase the free tier for now. Browse the links on the right side as well look in the documentation here for the data to be sent to train the model. Go here, enter your e-mail with which you signed-up and paste the primary key. Enter a project name and click ‘Add Project’. Add the required data (catalogue and usage file) to the project you created. Click on ‘New Build’. Interact and explore the model once it’s ready. If you are satisfied, follow the instructions in API documentation and embed the required code with in your online portal. Before going live, ensure you upgrade to the tier that better supports your expected usage.

Intermediate approach
Do all of the above in the basic approach. Plus, do this as well. Use Azure Data factory to build pipelines that take your data from source (private cloud, AX, NAV or CRM database or any other system) and send it to the recommendations API model.

Schedule these pipelines to execute at a regular time so that your data ingestion is automated. Note: these pipelines will run under your subscription and you will be billed for their usage. Check pricing here using the calculator here. If your solution design requires an intermediate Azure storage (between the source and recommendations API model) then you will also be billed for this storage account.
Now you have catalogue and usage data coming from your source system to the model in an automated fashion. However, how and where is your data in the source system itself? Since data requirements are minimal for this service, it’s fairly straightforward to have two separate tables or queries pulling data from your database. For Dynamics AX, you can use DIXF with AX2012 R2 and later versions to create two separate entities – one each for catalogue and sales and use these to provide the source data. DIXF will pull data out of product master tables and sales transaction tables and provide to ADF pipelines. For Dynamics AX2012 R3, you could also use the new yet-to-be-released capability called Entity store for AX2012 R3 as well as for new Dynamics AX.
Like already stated we will provide some code patterns for consumption experiences on various surfaces, however, since each application is unique you will be best served by engaging with a Microsoft Dynamics partner to create new forms on various clients as applicable.


Advanced approach
If you have scenarios where customers for company A should not see recommendations for products sold only through company B in your group, then you will most likely need to create multiple models. To create a solution like this you will also need to develop capability to monitor multiple models, interact with them as necessary, monitor what data jobs have completed/failed for which models and have multiple ADF pipes to feed to these models. You will also need multiple entities that provide data in your source database. We plan to provide some of these capabilities, in the interim if you need assistance please contact us.
As mentioned earlier recommendations API provides rule management for some rules like whitelists and blacklists. You will need to work with your partner to develop advanced integration scenarios like if you don’t want to show recommendations for products that are out of stock or if you will like to run an ATP (available-to-promise) check before displaying recommendations, or if you will like to maintain whitelists and blacklists dynamically, or if you will like to change whitelists and blacklists depending on customer, region, promotional campaigns etc.


When is the recommendation API available?
It’s available on azure marketplace here and you can start using it right away. Sign-up for the service and you can even try it for free for a limited number of API calls.

Customer story

Watch this video to see how JJ Foods uses recommendations API in their digital portal.

Watch the full JJ customer story video and read the case study.

Integration with Dynamics AX sales order - a teaser

Watch this video to see how you could integrate recommendation API to your Dynamics AX application. Please note that we produced this just as a sample integration for you to see the possibility of how an integration can be done. The code patterns or any other collateral that we will release in future will look different.

More details
Here are some more details on capabilities you could choose to add to your solution. All of these capabilities will need development effort. Once again, we plan to provide some of these patterns, however since each implementation will need unique elements, working with partners will provide you quicker turnaround.

Dynamics AX or NAV admin capabilities

  1. Ability for admin to see model ID inside AX or NAV application
  2. Ability for admin configure various model IDs per company in AX
  3. Ability for admins to provide a friendly name per model
  4. Ability to store primary key for the service subscription inside AX or NAV
  5. Ability to hide primary key from specific users

Data management capabilities

  1. UI to support ADF pipeline
  2. Creating and maintaining multiple ADF pipes
  3. Creating and maintaining multiple catalogue and usage files
  4. Drag-and-drop Dynamics AX DIXF entity creation by choosing optional features like product categories while supplying catalogue data
  5. Ability to use Dynamics AX Entity store for recommendations API in conjunction with other services developed using Cortana intelligence suite

Model management capabilities

  1. Ability to see model performance like number of recommendations provided, number of recommendations clicked, number of recommended items added to the basket in a given period per model
  2. Ability to select threshold and number of recommendations to be displayed per model on different surfaces/clients
  3. Ability to choose specific build per model
  4. Ability to go back to a previous build of a model
  5. Ability to choose specific build to be used per client

All customers’ sign-up for the service individually and are billed for the service as per the plan they choose. Customers are also billed for consumption of ADF and other services if utilized like Power BI & Azure Websites.

Known issues
AX2012/VS2012 issue

Robert Hanson, Luis-Cabrera Cordon, Dov Sheinker, Gaurav Roy, Akshey Gupta.



Skip to main content