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)

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