Recommendations API

The Recommendations API allows you to manage product recommendations in the Nilo platform. Recommendations are curated lists of products that can be displayed to specific stores during a defined time period.

Understanding Recommendations

Recommendations in Nilo help you highlight specific products to targeted stores:

• Recommendation Structure
  • Unique internal code for identification
  • Title and description for display
  • Weight for ordering (lower values appear first)
  • Validity period (start and end dates)
  • List of products to recommend
  • Store targeting through batch operations

Important Considerations

1. Unique Codes: Each recommendation requires a unique internal code
2. Weight Ordering: Lower weight values position the recommendation first in the list
3. Date Validity: Recommendations are only active within the start and end dates
4. Store Assignment: Use batch operations to assign recommendations to specific stores

Single Recommendation Operations

Get Recommendation Details

GET/recommendations/{code}

Retrieve detailed information about a specific recommendation.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the recommendation

Response Example

{
  "title": "Summer Recommendations",
  "internalCode": "REC-001",
  "description": "Best products for summer",
  "weight": 1,
  "startDate": "2025-01-01",
  "endDate": "2025-12-31",
  "enabled": true,
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Example Usage

Javascript

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations/REC-001",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations/REC-001"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

response = requests.get(url, headers=headers)
print(response.text)

List All Recommendations

GET/recommendations

Retrieve a list of all recommendations with pagination and filtering support.

Query Parameters

Parameter	Type	Required	Description
take	number	No	Number of items per page (default: 50, max: 50)
page	string	No	Page number (default: 1)
cursor	string	No	Cursor for pagination. First call should pass 0, subsequent calls use the cursor from the previous response
enabled	boolean	No	Filter by enabled status

Create or Update Recommendation

PUT/recommendations

Create a new recommendation or update an existing one. If the internalCode exists, it updates; otherwise, it creates a new recommendation.

Request Body Parameters

Parameter	Type	Required	Description
title	string	Yes	Title of the recommendation
internalCode	string	Yes	Unique identifier for the recommendation
description	string	Yes	Description of the recommendation
startDate	string	Yes	Start date (YYYY-MM-DD)
endDate	string	Yes	End date (YYYY-MM-DD)
weight	integer	No	Display order weight (lower values appear first, default: 0)
products	array	No	Array of products to include in the recommendation

Request Body Example

{
  "title": "Summer Recommendations",
  "internalCode": "REC-001",
  "description": "Best products for summer",
  "weight": 1,
  "startDate": "2025-06-01",
  "endDate": "2025-08-31",
  "products": [
    {
      "internalCode": "PROD-001"
    },
    {
      "internalCode": "PROD-002"
    }
  ]
}

Example Usage

Javascript

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  title: "Summer Recommendations",
  internalCode: "REC-001",
  description: "Best products for summer",
  weight: 1,
  startDate: "2025-06-01",
  endDate: "2025-08-31",
  products: [
    { internalCode: "PROD-001" },
    { internalCode: "PROD-002" },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations",
  {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/recommendations"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "title": "Summer Recommendations",
    "internalCode": "REC-001",
    "description": "Best products for summer",
    "weight": 1,
    "startDate": "2025-06-01",
    "endDate": "2025-08-31",
    "products": [
        {"internalCode": "PROD-001"},
        {"internalCode": "PROD-002"}
    ]
}

response = requests.put(url, headers=headers, json=data)
print(response.text)

Change Recommendation Status

PUT/recommendations/{code}/status

Enable or disable a specific recommendation.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the recommendation

Request Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	New status of the recommendation

Request Body Example

{
  "enabled": true
}

Batch Operations

Batch Update Recommendation Store Assignments

POST/batch/recommendations

Add or remove stores from recommendations in batch. This defines which stores will see specific recommendations.

Request Body Parameters

Parameter	Type	Required	Description
add	object	No	Stores to add to recommendations
remove	object	No	Stores to remove from recommendations

stores array items:

Field	Type	Required	Description
recommendationInternalCode	string	Yes	Internal code of the recommendation
storeInternalCode	string	Yes	Internal code of the store

Request Body Example

{
  "add": {
    "stores": [
      {
        "recommendationInternalCode": "REC-001",
        "storeInternalCode": "STORE-001"
      },
      {
        "recommendationInternalCode": "REC-001",
        "storeInternalCode": "STORE-002"
      }
    ]
  },
  "remove": {
    "stores": [
      {
        "recommendationInternalCode": "REC-002",
        "storeInternalCode": "STORE-003"
      }
    ]
  }
}

Response Codes

Code	Description
202	Request accepted, processing initiated
400	Bad request

Example Usage

Javascript

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  add: {
    stores: [
      {
        recommendationInternalCode: "REC-001",
        storeInternalCode: "STORE-001",
      },
    ],
  },
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/recommendations",
  {
    method: "POST",
    headers: headers,
    body: JSON.stringify(data),
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/batch/recommendations"

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "add": {
        "stores": [
            {
                "recommendationInternalCode": "REC-001",
                "storeInternalCode": "STORE-001"
            }
        ]
    }
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Security

Authentication

All endpoints require two types of authentication:

• API Key in header: x-api-key
• Authorization token in header: Authorization

Required Permissions

• For reading operations: supplier/recommendation.read
• For writing operations: supplier/recommendation.write
• For batch operations: supplier/recommendation.bulkwrite