Stock Groupers API

The Stock Groupers API allows you to manage stock groupers in the Nilo platform. Stock groupers represent warehouses or depots that serve specific stores. These endpoints help you create, update, and manage stock groupers for inventory distribution.

Understanding Stock Groupers

Stock Groupers in Nilo represent warehouses or distribution centers:

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

Important Considerations

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

Single Grouper Operations

Create Stock Grouper

POST/grouper/stock

Creates a new stock 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/stock", {
  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/stock"

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 Stock Grouper

PUT/grouper/{code}/stock

Updates an existing stock 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/stock", {
  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/stock"

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 Stock Grouper Status

PUT/grouper/{code}/status/stock

Enable or disable a specific stock 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/stock", {
  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/stock"

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 Stock Grouper Store Assignments

POST/batch/grouper/stock

Add or remove stores from stock groupers in a single operation. This defines which stores are served by which warehouse.

Request Body Parameters

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

stores array items:

Field	Type	Required	Description
groupInternalCode	string	Yes	Internal code of the grouper
storeInternalCode	string	Yes	Internal code of the store

Request Body Example

{
  "add": {
    "stores": [
      {
        "groupInternalCode": "WAREHOUSE-001",
        "storeInternalCode": "STORE-123"
      },
      {
        "groupInternalCode": "WAREHOUSE-001",
        "storeInternalCode": "STORE-456"
      }
    ]
  },
  "remove": {
    "stores": [
      {
        "groupInternalCode": "WAREHOUSE-002",
        "storeInternalCode": "STORE-789"
      }
    ]
  }
}

Response Codes

Code	Description
202	Request accepted, processing initiated
402	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: [
      {
        groupInternalCode: "WAREHOUSE-001",
        storeInternalCode: "STORE-123",
      },
    ],
  },
  remove: {
    stores: [
      {
        groupInternalCode: "WAREHOUSE-002",
        storeInternalCode: "STORE-789",
      },
    ],
  },
};

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

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

data = {
    "add": {
        "stores": [
            {
                "groupInternalCode": "WAREHOUSE-001",
                "storeInternalCode": "STORE-123"
            }
        ]
    },
    "remove": {
        "stores": [
            {
                "groupInternalCode": "WAREHOUSE-002",
                "storeInternalCode": "STORE-789"
            }
        ]
    }
}

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

Stock vs Stock Groupers

This endpoint manages store assignments to stock groupers. To update product availability within a grouper, use the /batch/stock/grouper endpoint in the Stock section.

Batch Upsert Stock Groupers

POST/batch/grouper/stock/upsert

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

Use this endpoint when you need to:

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

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of stock 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": "Warehouse Central",
      "internalCode": "STOCK-GRP-001",
      "enabled": true
    },
    {
      "name": "Warehouse North",
      "internalCode": "STOCK-GRP-002",
      "enabled": true
    },
    {
      "name": "Warehouse Inactive",
      "internalCode": "STOCK-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: "Warehouse Central",
      internalCode: "STOCK-GRP-001",
      enabled: true,
    },
    {
      name: "Warehouse North",
      internalCode: "STOCK-GRP-002",
      enabled: true,
    },
  ],
};

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

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

data = {
    "upsert": [
        {
            "name": "Warehouse Central",
            "internalCode": "STOCK-GRP-001",
            "enabled": True
        },
        {
            "name": "Warehouse North",
            "internalCode": "STOCK-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": "STOCK_GROUP_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "STOCK_GROUP_NOT_FOUND",
    "message": "Stock group not found",
    "entity": "stockGroup",
    "entityCode": "STOCK-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
STOCK_GROUP_NOT_FOUND	The stock 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 stock grouper with the same name already exists
INTERNAL_CODE_ALREADY_EXIST	A stock grouper with the same internal code already exists
STORE_ALREADY_IN_STOCK_GROUP	The store is already assigned to this stock grouper
STORE_NOT_IN_STOCK_GROUP	The store is not assigned to this stock 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 stock grouper endpoints, the following permissions are required:

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