1. Using Oracle Commerce
  2. Manage Your Catalog
  3. Work with the Recommendations API

Work with the Recommendations API

Use the Recommendations REST API to update visitor tracking state and optionally request recommendations.

The Oracle Commerce Recommendations service provides personalized product recommendations to shoppers based on behavior on Commerce storefronts. Product recommendations are generated by an AI-powered learning engine trained for a wide variety of ecommerce models with a proven record of increased conversion rate and average order value.

The Recommendations API lets storefront applications feed shopper behavioral information to the engine, and to get back personalized product recommendations which the application can then display to the shopper.

The API exposes a single endpoint, whose payload can perform multiple operations simultaneously. This allows the engine to reduce the number of HTTP transactions between the application and the service, which optimizes latency, providing a better experience for shoppers.

The host of the Recommendations endpoint can be retrieved from the Commerce Store API getExternalServiceData endpoint, using the production-Recommendations resource. The response will include a protocol, host, port, and path to the Recommendations API.

For example, suppose you issue the following request:

GET /ccstore/v1/merchant/production-Recommendations

Commerce returns the a response similar to this sample:

{
"serverType": "production",
"serviceData": {
"protocol": "https",
"host": "recs.occa.eu-frankfurt-1.ocs.oraclecloud.com",
"port": 443,
"path": "pr",
"displayName": "Oracle Recommendations",
"name":"Recommendations",
"tenantId":"l01234567c1PRD"
},
"links": [{
"rel":"self",
"href":"https://example.com/ccstore/v1/merchant/production-Recommendations"
}],
"id":"production-Recommendations"
}

The serviceData object in the response contains the information necessary to construct the URL to the Recommendations API endpoint. This information will rarely change for a given tenant, but it may change on occasion if required by the backing infrastructure. Therefore, it is best to issue a request to the getExternalServiceData endpoint at the start of each user session . Once the Recommendations URL has been constructed, requests to the Recommendations service can be made to the Recommendations endpoint. 

POST /pr/v4/sessions/click

The request body is a JSON payload that contains some top level properties for the overall request, and a series of operational properties that update the shopper’s state and request recommendations for the shopper. For details about these properties, see the Commerce REST API documentation that is available in the Oracle Help Center.

In the following sample request, the shopper visits the store’s home page and then clicks a product link. The storefront application should issue two requests to the Recommendations service, one for each page view (the home page and the product details page.)

When the shopper lands on the home page, the client should issue the following request:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD",
"catalogId": "mysiteCatalog",
"view": {
"url": "https://mysite.example.com",
"pageTitle": "Mysite Home Page",
"referrer": "https://search.example.com?q=mysite"
}
}

The Recommendations service records that information, and returns a response like the following:

200 OK
{
"token": "aaabbbcccddd"
}

The token in the response contains state information useful to the Recommendations service, and should be provided in the subsequent request. All POST /pr/v4/sessions/click requests will include the token property in the response. The value of the token property is not guaranteed to be the same from request to request. The application must always provide the token from the most recent response. In addition, the token should be persisted between shopper sessions, if possible . This helps maintain recommendations continuity for a shopper across sessions.

Continuing with the previous example, when the shopper clicks the product link on the home page, the application should inform the Recommendations service using the following request:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Red Shirt",
"referrer": "https://mysite.example.com", "productId": "p02113
}
}

Notice the additional property productId in the request. This tells the recommender that the shopper is looking at a product on its details page. This is useful information, and is considered by the Recommendations service the next time the application requests recommendations for this shopper. The recommendations service sends the following response. (In this example, it’s the same value as returned in the previous sample response, but it may change occasionally.)

Commerce lets you create complex recommendation strategies in the administration interface. Suppose you created recommendation strategies that specified recommendations appear on the product detail page. This request can be modified to ask the recommender for recommendations. The modified request would look like this:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD",
"token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Red Shirt",
"referrer": "https://mysite.example.com", "productId": "p02113"
},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
}
}
}

That recommendations section will let the service know that you want some product recommendations in the response. With the latest data, the service will generate personalized recommendations for the shopper, with a response like the following:

200 OK
{
"token": "aaabbbcccddd", "recommendations": {
"pdpRecs": {
"recSetId": "342bf3789:32-5",
"recs": [
{ "productId": "p34909" },
{ "productId": "p28200" },
{ "productId": "p11879" },
{ "productId": "p00032" },
{ "productId": "p00877" },
{ "productId": "p21006" }
]
}
}
}

Detailed information about those products (like the localized display name, product images, and prices for this shopper) can be obtained with API requests to the Commerce Storefront server. You may also choose to have your application cache this information locally.

Multiple recommendation sets can be requested in a single HTTP transaction. For example, if your application has an additional space on the page for recommendations and you want to use a different strategy, an example request payload might look like this:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Red Shirt",
"referrer": "https://mysite.example.com", "productId": "p02113"
},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
},
"top": {
"numRecs": 4, "strategy": "topSellers"
}
}
}

The Recommendations service will not recommend the same products in multiple recommendations sets in the same request. This prevents the application from showing the shopper the same product in multiple places on a page.

If a shopper clicks a recommended product, the engine would like to know about it. This is an important piece of feedback, and lets the engine know that the shopper showed interest in a recommended product. Suppose the shopper clicked on the product whose ID is p11879 from the request. The application will show the product details for that product, and should issue a request to the Recommendations service. (The response to this request includes an additional set of recommendations.)

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "https://mysite.example.com/comfy-sandals/p11879", "referrer": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Comfy Sandals",
"productId": "p11879"
},
"click": {
"recSetId": "342bf3789:32-5",
"productId": "p11879"
},
"recommendations": {
...
}

}

Your application should notify the Recommendations service if the contents of the shopper’s cart changes, for example, when they add or remove an item. The current cart contents are taken into account when personalized recommendations are made, so it is best to keep the service up to date with a request like the following sample:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "view": {
"url": "https://mysite.example.com/comfy-sandals/p11879", "referrer": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Comfy Sandals",
"productId": "p11879"
},
"cart": {
"productIds": [ "p11879" ], "totalPrice": 48.99, "pricelistGroupId": "sunnysideStore", "currencyCode": "USD"
},
"recommendations": {
...
}
}

This request returns the usual response, with a (possibly changed) token and a fresh set of recommendations, which may be affected by the contents of the cart.

Similarly, if the shopper makes a purchase, this is useful information for the recommendations service. The application should issue a request to the endpoint to indicate that a checkout has occurred.

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "checkout": {
"products": [{ "productId": "p11879", "quantity": 1,
"price": 48.99
},{
"productId": "p02113", "quantity": 1,
"price": 35
}],

"totalPrice":   83.99, "pricelistGroupId": "sunnysideStore", "currencyCode": "USD"
}
}

Commerce responds with the standard response with the token:

200 OK
{
"token": "aaabbbcccddd"
}

If an error occurs due to an invalid input, the response will include the HTTP 400 status code and a short, diagnostic message. These messages are not a part of the API, and they are not intended to be displayed to shoppers. For example:

400 Bad Request
{
"token": "aaabbbcccddd",
"error": "Missing URL in view request."
}

Likewise, if there is an internal service error, the response will include the HTTP 500 status code, and will not return a token. The most recently-returned token should still be used in the next request. For example:

500 Internal Service Error
{
"error": "Something went wrong, ops has been notified."
}

If the shopper’s profile ID is known to the client application, you can pass it in the request as a top level property. This allows for personalized recommendations for the user across different clients, for example, a web browser and a custom headless application. If the user has logged into the client application, each request can include the profile ID, as shown in this example:

POST /pr/v4/sessions/click
{
"tenantId": "p01234567c1PRD", "token": "aaabbbcccddd", "catalogId": "mysiteCatalog", "profileId":  "p271123", "view": {
"url": "https://mysite.example.com/red-shirt/p02113", "pageTitle": "Mysite: Red Shirt",

"referrer": "https://mysite.example.com", "productId": "p02113"
},
"recommendations": { "pdpRecs": {
"numRecs": 6,
"strategy": "inCollection"
},
"top": {
"numRecs": 4, "strategy": "topSellers"
}
}
}

In this sample request, the catalogId property is used when the Commerce instance has multiple catalogs, for example, when the instance supports multiple brand sites or country sites. The Recommendations engine uses catalogId to restrict recommendations to products that are available only in the specified catalog.