Point Lists API

The Point Lists API allows you to manage point-based loyalty programs in the Nilo platform. Point lists define which products award loyalty points and how many points each product is worth.

Understanding Point Lists

Point lists in Nilo are containers that associate products with point values:

Point List Structure
- Unique internal code for identification
- Name for display purposes
- Enabled/disabled status
- Product associations with unit and point values
Product-Point Associations
- Each product is linked to a point list by its internal code
- Units define how many items need to be purchased
- Points define the reward given per qualifying purchase

Important Considerations

Unique Codes: Each point list requires a unique internal code
Product Mapping: Products are associated to point lists via their internal codes
Unit Thresholds: The units field determines the minimum quantity for points to be awarded
Points Value: Points are integer values (no decimals)
Loyalty Groups: Point lists can be linked to loyalty groups for segmented rewards

Batch Operations

Batch Upsert Point Lists

POST/batch/pointlist/upsert

This endpoint allows you to create or update multiple point lists at once. The operation is processed asynchronously.

Use this endpoint when you need to:

Create multiple point list containers simultaneously
Synchronize point list configurations from your loyalty system
Enable or disable point lists in bulk

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of point list objects
upsert[].internalCode	string	Yes	Unique point list code
upsert[].name	string	Yes	Point list display name
upsert[].enabled	boolean	Yes	Whether the point list is active

Request Body Example

{
  "upsert": [
    {
      "internalCode": "POINTS-GOLD",
      "name": "Gold Members Points",
      "enabled": true
    },
    {
      "internalCode": "POINTS-SILVER",
      "name": "Silver Members Points",
      "enabled": true
    },
    {
      "internalCode": "POINTS-PROMO",
      "name": "Promotional Points",
      "enabled": false
    }
  ]
}

Response Codes

Code	Description
202	Request accepted, processing initiated
400	Bad request - Invalid parameters
403	Forbidden - Insufficient permissions

Response Example

{
  "batchIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

Example Usage

Javascript
Python

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

const data = {
  upsert: [
    {
      internalCode: "POINTS-GOLD",
      name: "Gold Members Points",
      enabled: true,
    },
    {
      internalCode: "POINTS-SILVER",
      name: "Silver Members Points",
      enabled: true,
    },
  ],
};

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

import requests

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

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

data = {
    "upsert": [
        {
            "internalCode": "POINTS-GOLD",
            "name": "Gold Members Points",
            "enabled": True
        },
        {
            "internalCode": "POINTS-SILVER",
            "name": "Silver Members Points",
            "enabled": True
        }
    ]
}

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

Batch Upsert Products to Point Lists

POST/batch/pointlist/upsert/product

This endpoint allows you to associate multiple products with point lists at once, defining how many points each product awards. The operation is processed asynchronously.

Use this endpoint when you need to:

Assign point values to multiple products simultaneously
Update point rewards across your product catalog
Synchronize product-point associations from your loyalty system

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of product-point association objects
upsert[].pointListInternalCode	string	Yes	Point list internal code to associate the product to
upsert[].productInternalCode	string	Yes	Product internal code
upsert[].units	integer	Yes	Minimum units required to earn points (min: 1)
upsert[].points	integer	Yes	Points awarded per qualifying purchase (min: 0)

Request Body Example

{
  "upsert": [
    {
      "pointListInternalCode": "POINTS-GOLD",
      "productInternalCode": "PROD-001",
      "units": 1,
      "points": 10
    },
    {
      "pointListInternalCode": "POINTS-GOLD",
      "productInternalCode": "PROD-002",
      "units": 2,
      "points": 25
    },
    {
      "pointListInternalCode": "POINTS-SILVER",
      "productInternalCode": "PROD-001",
      "units": 1,
      "points": 5
    }
  ]
}

Response Codes

Code	Description
202	Request accepted, processing initiated
400	Bad request - Invalid parameters
403	Forbidden - Insufficient permissions

Response Example

{
  "batchIds": ["550e8400-e29b-41d4-a716-446655440000"]
}

Example Usage

Javascript
Python

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

const data = {
  upsert: [
    {
      pointListInternalCode: "POINTS-GOLD",
      productInternalCode: "PROD-001",
      units: 1,
      points: 10,
    },
    {
      pointListInternalCode: "POINTS-GOLD",
      productInternalCode: "PROD-002",
      units: 2,
      points: 25,
    },
    {
      pointListInternalCode: "POINTS-SILVER",
      productInternalCode: "PROD-001",
      units: 1,
      points: 5,
    },
  ],
};

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

import requests

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

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

data = {
    "upsert": [
        {
            "pointListInternalCode": "POINTS-GOLD",
            "productInternalCode": "PROD-001",
            "units": 1,
            "points": 10
        },
        {
            "pointListInternalCode": "POINTS-GOLD",
            "productInternalCode": "PROD-002",
            "units": 2,
            "points": 25
        },
        {
            "pointListInternalCode": "POINTS-SILVER",
            "productInternalCode": "PROD-001",
            "units": 1,
            "points": 5
        }
    ]
}

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

Error Codes

When an operation fails, the API returns a structured error response:

{
  "code": 404,
  "message": "POINT_LIST_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "POINT_LIST_NOT_FOUND",
    "message": "Point list not found",
    "entity": "pointList",
    "entityCode": "PLIST-001",
    "timestamp": "2026-05-18T15:16:47.000Z"
  }
}

The object field provides additional context about the error:

Field	Description
`statusCode`	HTTP status code
`code`	Error code (same as top-level `message`)
`message`	Human-readable error description
`entity`	Entity type that caused the error
`entityCode`	The internalCode of the entity involved
`timestamp`	When the error occurred (ISO 8601)

404 — Not Found

Error Code	Description
`POINT_LIST_NOT_FOUND`	The point list does not exist
`PRODUCT_NOT_FOUND`	The product specified does not exist

400 — Bad Request

Error Code	Description
`POINTS_NOT_INTEGER_BIGGER_THAN_ZERO`	Points value must be a positive integer

409 — Conflict

Error Code	Description
`POINT_LIST_ALREADY_EXIST`	A point list with the same internal code already exists
`POINT_LIST_NAME_ALREADY_EXIST`	A point list with the same name already exists
`INTERNAL_CODE_ALREADY_EXIST`	A point list with the same internal code already exists
`PRODUCT_ALREADY_IN_POINT_LIST`	The product is already associated with this point list
`PRODUCT_NOT_IN_POINT_LIST`	The product is not in this point list (when trying to remove)

Security

Authentication

All endpoints require two types of authentication:

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

Required Permissions

For point list operations: supplier/pointlist.bulkwrite

Understanding Point Lists​

Important Considerations​

Batch Operations​

Batch Upsert Point Lists​

Request Body Parameters​

Request Body Example​

Response Codes​

Response Example​

Example Usage​

Batch Upsert Products to Point Lists​

Request Body Parameters​

Request Body Example​

Response Codes​

Response Example​

Example Usage​

Error Codes​

404 — Not Found​

400 — Bad Request​

409 — Conflict​

Security​

Authentication​

Required Permissions​

Tana

Understanding Point Lists

Important Considerations

Batch Operations

Batch Upsert Point Lists

Request Body Parameters

Request Body Example

Response Codes

Response Example

Example Usage

Batch Upsert Products to Point Lists

Request Body Parameters

Request Body Example

Response Codes

Response Example

Example Usage

Error Codes

404 — Not Found

400 — Bad Request

409 — Conflict

Security

Authentication

Required Permissions