Promotion Groupers API

The Promotion Groupers API allows you to manage promotion groupers in the Nilo platform. Promotion groupers represent commercial segmentations that determine which stores can see specific promotions.

Understanding Promotion Groupers

Promotion Groupers in Nilo represent commercial segments for targeting promotions:

• Grouper Structure
  • Unique internal code for identification (same as segment code in your ERP)
  • Name for display and organization
  • Status (enabled/disabled)
  • Store associations (which stores belong to this segment)

Important Considerations

1. Unique Codes: Each grouper requires a unique internal code (typically your commercial segment code from ERP)
2. Store Associations: Groupers define which stores can see promotions assigned to them
3. Status Management: Groupers can be enabled or disabled without deletion
4. Batch Operations: Support for bulk store assignment/removal

Single Grouper Operations

Create Promotion Grouper

POST/grouper/promotion

Creates a new promotion grouper in the Nilo platform.

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Name of the grouper
internalCode	string	Yes	Unique identifier for grouper

Request Body Example

{
  "name": "Grouper 1",
  "internalCode": "1235"
}

Example Usage

Javascript

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

const data = {
  name: "Grouper 1",
  internalCode: "1235",
};

fetch("https://api.nilo.com/grouper/promotion", {
  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://api.nilo.com/grouper/promotion"

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

data = {
    "name": "Grouper 1",
    "internalCode": "1235"
}

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

Update Promotion Grouper

PUT/grouper/{code}/promotion

Updates an existing promotion grouper.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Grouper code to update

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	New name of grouper

Request Body Example

{
  "name": "Grouper 1"
}

Example Usage

Javascript

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

const data = {
  name: "Grouper 1",
};

fetch("https://api.nilo.com/grouper/7234/promotion", {
  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://api.nilo.com/grouper/7234/promotion"

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

data = {
    "name": "Grouper 1"
}

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

Change Promotion Grouper Status

PUT/grouper/{code}/status/promotion

Enable or disable a specific promotion grouper.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Grouper code

Request Body Parameters

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

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: true,
};

fetch("https://api.nilo.com/grouper/7234/status/promotion", {
  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://api.nilo.com/grouper/7234/status/promotion"

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

data = {
    "enabled": True
}

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

Batch Operations

Batch Update Promotion Groupers

POST/batch/grouper/promotion

Update multiple promotion groupers in a single operation.

Request Body Parameters

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

Request Body Example

{
  "add": {
    "stores": [
      {
        "groupInternalCode": "2345",
        "storeInternalCode": "124f"
      }
    ]
  },
  "remove": {
    "stores": [
      {
        "groupInternalCode": "2345",
        "storeInternalCode": "125f"
      }
    ]
  }
}

Example Usage

Javascript

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

const data = {
  add: {
    stores: [
      {
        groupInternalCode: "2345",
        storeInternalCode: "124f",
      },
    ],
  },
  remove: {
    stores: [
      {
        groupInternalCode: "2345",
        storeInternalCode: "125f",
      },
    ],
  },
};

fetch("https://api.nilo.com/batch/grouper/promotion", {
  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://api.nilo.com/batch/grouper/promotion"

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

data = {
    "add": {
        "stores": [
            {
                "groupInternalCode": "2345",
                "storeInternalCode": "124f"
            }
        ]
    },
    "remove": {
        "stores": [
            {
                "groupInternalCode": "2345",
                "storeInternalCode": "125f"
            }
        ]
    }
}

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

Batch Upsert Promotion Groupers

POST/batch/grouper/promotion/upsert

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

Use this endpoint when you need to:

• Synchronize your promotion grouper structure from your ERP system
• Create or update multiple promotion groupers simultaneously
• Perform bulk imports of promotion grouper configurations

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of promotion grouper objects
upsert[].name	string	Yes	Grouper name
upsert[].internalCode	string	Yes	Unique grouper code (same as in ERP)
upsert[].enabled	boolean	Yes	Whether the grouper is active

Request Body Example

{
  "upsert": [
    {
      "name": "Region North Promotions",
      "internalCode": "PROMO-GRP-001",
      "enabled": true
    },
    {
      "name": "Region South Promotions",
      "internalCode": "PROMO-GRP-002",
      "enabled": true
    },
    {
      "name": "Special Channel",
      "internalCode": "PROMO-GRP-003",
      "enabled": false
    }
  ]
}

Response Codes

Code	Description
202	Request accepted, processing initiated
402	Bad request - Invalid parameters

Response Example

{
  "code": 202,
  "batchIds": {},
  "message": "Operation in processing"
}

Example Usage

Javascript

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

const data = {
  upsert: [
    {
      name: "Region North Promotions",
      internalCode: "PROMO-GRP-001",
      enabled: true,
    },
    {
      name: "Region South Promotions",
      internalCode: "PROMO-GRP-002",
      enabled: true,
    },
  ],
};

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

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

data = {
    "upsert": [
        {
            "name": "Region North Promotions",
            "internalCode": "PROMO-GRP-001",
            "enabled": True
        },
        {
            "name": "Region South Promotions",
            "internalCode": "PROMO-GRP-002",
            "enabled": True
        }
    ]
}

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": "PROMOTION_GROUP_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "PROMOTION_GROUP_NOT_FOUND",
    "message": "Promotion group not found",
    "entity": "promotionGroup",
    "entityCode": "PROMO-GRP-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
PROMOTION_GROUP_NOT_FOUND	The promotion grouper does not exist
STORE_NOT_FOUND	The store specified in the operation does not exist

409 — Conflict

Error Code	Description
NAME_ALREADY_EXIST	A promotion grouper with the same name already exists
INTERNAL_CODE_ALREADY_EXIST	A promotion grouper with the same internal code already exists
STORE_ALREADY_IN_PROMOTION_GROUP	The store is already assigned to this promotion grouper
STORE_NOT_IN_PROMOTION_GROUP	The store is not assigned to this promotion grouper (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 promotion grouper endpoints, the following permissions are required:

• For write operations: supplier/grouper.write
• For batch operations: supplier/grouper.bulkwrite