Loyalty Challenges API

The Loyalty Challenges API allows you to manage loyalty programs and challenges in the Nilo platform. Loyalty challenges reward customers with points when they purchase specific products and reach a required amount.

Understanding Loyalty Challenges

Loyalty Challenges in Nilo are gamified promotions that reward customers:

• Challenge Structure
  • Unique internal code for identification
  • Title and description for display
  • Points given as reward
  • Required purchase amount to achieve the challenge
  • Validity period (start and end dates)
  • List of products that qualify for the challenge

Important Considerations

1. Unique Codes: Each challenge requires a unique internal code (same as in your ERP)
2. Points System: Define how many points customers earn when completing the challenge
3. Required Amount: Set the minimum purchase amount needed to complete the challenge
4. Product Scope: Specify which products count towards the challenge
5. Date Validity: Challenges are only active within the start and end dates

Single Challenge Operations

Get Loyalty Challenge Details

GET/loyaltychallenge/{code}

Retrieve detailed information about a specific loyalty challenge.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the loyalty challenge

Response Example

{
  "id": 1,
  "title": "Summer Points Challenge",
  "description": "Earn points on summer products",
  "image": "https://example.com/challenge.jpg",
  "internalCode": "CHALLENGE-001",
  "pointsGiven": 100,
  "requiredMoney": 500,
  "enabled": true,
  "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",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/loyaltychallenge/CHALLENGE-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/loyaltychallenge/CHALLENGE-001"

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

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

List All Loyalty Challenges

GET/loyaltychallenge

Retrieve a list of all loyalty challenges 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
from	string	No	Start date filter (YYYY-MM-DD)
to	string	No	End date filter (YYYY-MM-DD)

Create or Update Loyalty Challenge

PUT/loyaltychallenge

Create a new loyalty challenge or update an existing one.

Request Body Parameters

Parameter	Type	Required	Description
title	string	Yes	Title of the challenge
internalCode	string	Yes	Unique identifier for the challenge
description	string	No	Description of the challenge
image	string	No	URL of the challenge image
pointsGiven	number	Yes	Points awarded when challenge is completed
requiredAmount	number	Yes	Minimum purchase amount to complete challenge
start	string	Yes	Start date (YYYY-MM-DD)
end	string	Yes	End date (YYYY-MM-DD)
enabled	boolean	Yes	Whether the challenge is active
products	array	Yes	Array of products that qualify for the challenge

Request Body Example

{
  "title": "Summer Points Challenge",
  "internalCode": "CHALLENGE-001",
  "description": "Earn 100 points when you spend $500 on summer products",
  "image": "https://example.com/challenge.jpg",
  "pointsGiven": 100,
  "requiredAmount": 500,
  "start": "2025-06-01",
  "end": "2025-08-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",
  "Content-Type": "application/json",
};

const data = {
  title: "Summer Points Challenge",
  internalCode: "CHALLENGE-001",
  description: "Earn 100 points when you spend $500 on summer products",
  image: "https://example.com/challenge.jpg",
  pointsGiven: 100,
  requiredAmount: 500,
  start: "2025-06-01",
  end: "2025-08-31",
  enabled: true,
  products: [
    { internalCode: "PROD-001" },
    { internalCode: "PROD-002" },
  ],
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/loyaltychallenge",
  {
    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/loyaltychallenge"

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

data = {
    "title": "Summer Points Challenge",
    "internalCode": "CHALLENGE-001",
    "description": "Earn 100 points when you spend $500 on summer products",
    "image": "https://example.com/challenge.jpg",
    "pointsGiven": 100,
    "requiredAmount": 500,
    "start": "2025-06-01",
    "end": "2025-08-31",
    "enabled": True,
    "products": [
        {"internalCode": "PROD-001"},
        {"internalCode": "PROD-002"}
    ]
}

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

Change Loyalty Challenge Status

PUT/loyaltychallenge/{code}/status

Enable or disable a specific loyalty challenge.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the loyalty challenge

Request Body Parameters

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

Request Body Example

{
  "enabled": true
}

Example Usage

Javascript

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

const data = {
  enabled: false,
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/loyaltychallenge/CHALLENGE-001/status",
  {
    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/loyaltychallenge/CHALLENGE-001/status"

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

data = {
    "enabled": False
}

response = requests.put(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/loyaltychallenge.read
• For writing operations: supplier/loyaltychallenge.write