Categories and Subcategories API

The Categories and Subcategories API allows you to manage the product categorization structure on the Nilo platform. These endpoints are essential for organizing products in the store.

Understanding Categories and Subcategories

Categories and subcategories in Nilo form a hierarchical structure that helps organize products effectively:

Categories: Top-level classifications that group related products
- Can contain multiple subcategories
- Have properties like name, internal code, weight, and image
- Can be enabled/disabled to control visibility
- Used for primary navigation and product organization
Subcategories: Second-level classifications within categories
- Must belong to a parent category
- Help create more specific product groupings
- Share similar properties with categories
- Enable more granular product organization

Important Considerations

Unique Codes: Both categories and subcategories require unique internal codes
Hierarchy: Subcategories must always have a valid parent category
Weight: Used for controlling display order in listings (lower numbers appear first)
Status: Both can be enabled/disabled independently
Images: Categories can have associated images for better visual representation

Single Operations

Get all categories

GET/category

This endpoint allows you to retrieve all available categories on the platform.

Query Parameters

Parameter	Type	Required	Description
take	number	No	Number of items per page (maximum 50, minimum 1, default 50)
page	string	No	Page number (default 1)
enabled	boolean	No	Filter by enabled status
cursor	string	No	Cursor for pagination. First call use 0, then use the cursor from the previous response

Response Codes

Code	Description
200	Successful operation - Categories retrieved
404	Not found - Categories not found

Example Usage

Javascript
Python

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

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category?take=10&page=1&enabled=true",
  {
    method: "GET",
    headers: headers,
  }
)
  .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/category"

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

params = {
    'take': 10,
    'page': 1,
    'enabled': True
}

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

Success Response Example

{
  "data": [
    {
      "name": "Category",
      "internalCode": "1235",
      "image": "/qa/category/12442.png",
      "enabled": true,
      "children": [
        {
          "name": "Children Category",
          "internalCode": "1236"
        }
      ]
    }
  ],
  "page": {
    "pageBased": {
      "count": 230
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Get a specific category

GET/category/{code}

This endpoint allows you to retrieve the details of a specific category.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Category code

Response Codes

Code	Description
200	Successful operation - Category retrieved
404	Not found - Category not found

Example Usage

Javascript
Python

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

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/category/7234",
  {
    method: "GET",
    headers: headers,
  }
)
  .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/category/7234"

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

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

Success Response Example

{
  "name": "Category",
  "internalCode": "7234",
  "image": "/qa/category/12442.png",
  "enabled": true,
  "parent": {
    "name": "Parent Category",
    "internalCode": "1235"
  },
  "children": [
    {
      "name": "Children Category",
      "internalCode": "1236"
    }
  ]
}

Create a category

POST/category

This endpoint allows you to create a new category on the platform.

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Category name
internalCode	string	Yes	Internal category code
weight	integer	No	Value used for product positioning in listings (order of appearance)
image	string	No	Public URL of the category image

Image Management

The image field expects a public and accessible URL. During processing, Nilo will download the image, store it on Nilo servers, and distribute it through a CDN for optimized loading. Use high-quality images - the platform will automatically generate optimized versions for different devices.

Request Body Example

{
  "name": "New Category",
  "internalCode": "9876",
  "weight": 1,
  "image": "/qa/category/9876.png"
}

Response Codes

Code	Description
200	Successful operation - Category created
404	Not found - Error creating category

Example Usage

Javascript
Python

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

const data = {
  name: "New Category",
  internalCode: "9876",
  weight: 1,
  image: "/qa/category/9876.png",
};

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

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

data = {
    "name": "New Category",
    "internalCode": "9876",
    "weight": 1,
    "image": "/qa/category/9876.png"
}

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

Update a category

PUT/category/{code}

This endpoint allows you to update an existing category.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Category code

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Category name
weight	integer	No	Value used for product positioning in listings (order of appearance)
image	string	No	Public URL of the category image

Image Management

The image field expects a public and accessible URL. During processing, Nilo will download the image, store it on Nilo servers, and distribute it through a CDN for optimized loading.

Request Body Example

{
  "name": "Updated Category",
  "weight": 2,
  "image": "/qa/category/updated.png"
}

Response Codes

Code	Description
200	Successful operation - Category updated
404	Not found - Category not found

Example Usage

Javascript
Python

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

const data = {
  name: "Updated Category",
  weight: 2,
  image: "/qa/category/updated.png",
};

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

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

data = {
    "name": "Updated Category",
    "weight": 2,
    "image": "/qa/category/updated.png"
}

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

Upsert category

PUT/category

This endpoint allows you to create or update an existing category (upsert).

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Category name
internalCode	string	Yes	Internal category code
enabled	boolean	Yes	Category enabled status
weight	integer	No	Value used for product positioning in listings (order of appearance)
image	string	No	Public URL of the category image

Image Management

The image field expects a public and accessible URL. During processing, Nilo will download the image, store it on Nilo servers, and distribute it through a CDN for optimized loading.

Request Body Example

{
  "name": "Upsert Category",
  "internalCode": "5678",
  "enabled": true,
  "weight": 3,
  "image": "/qa/category/upsert.png"
}

Response Codes

Code	Description
200	Successful operation - Category updated
404	Not found - Category not found

Example Usage

Javascript
Python

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

const data = {
  name: "Upsert Category",
  internalCode: "5678",
  enabled: true,
  weight: 3,
  image: "/qa/category/upsert.png",
};

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

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

data = {
    "name": "Upsert Category",
    "internalCode": "5678",
    "enabled": true,
    "weight": 3,
    "image": "/qa/category/upsert.png"
}

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

Change category status

PUT/category/{code}/status

This endpoint allows you to enable or disable a category.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Category code

Request Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	Enabled status (true/false)

Request Body Example

{
  "enabled": true
}

Response Codes

Code	Description
200	Successful operation - Status updated
404	Not found - Category not found

Example Usage

Javascript
Python

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

const data = {
  enabled: true,
};

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

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

data = {
    "enabled": true
}

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

Subcategories

Create a subcategory

POST/subcategory

This endpoint allows you to create a new subcategory on the platform.

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Subcategory name
internalCode	string	Yes	Internal subcategory code
parentCategoryInternalCode	string	Yes	Internal code of the parent category
weight	integer	No	Value used for product positioning in listings (order of appearance)

Request Body Example

{
  "name": "New Subcategory",
  "internalCode": "4321",
  "parentCategoryInternalCode": "7234",
  "weight": 1
}

Response Codes

Code	Descripción
200	Successful operation - Subcategory created
404	Not found - Error creating subcategory

Example Usage

Javascript
Python

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

const data = {
  name: "New Subcategory",
  internalCode: "4321",
  parentCategoryInternalCode: "7234",
  weight: 1,
};

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

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

data = {
    "name": "New Subcategory",
    "internalCode": "4321",
    "parentCategoryInternalCode": "7234",
    "weight": 1
}

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

Update a subcategory

PUT/subcategory/{code}

This endpoint allows you to update an existing subcategory.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Subcategory code

Request Body Parameters

Parameter	Type	Required	Descripción
name	string	Yes	Subcategory name
parentCategoryInternalCode	string	Yes	Internal code of the parent category
weight	integer	No	Value used for product positioning in listings (order of appearance)

Request Body Example

{
  "name": "Updated Subcategory",
  "parentCategoryInternalCode": "7234",
  "weight": 2
}

Response Codes

Code	Descripción
200	Successful operation - Subcategory updated
404	Not found - Subcategory not found

Example Usage

Javascript
Python

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

const data = {
  name: "Updated Subcategory",
  parentCategoryInternalCode: "7234",
  weight: 2,
};

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

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

data = {
    "name": "Updated Subcategory",
    "parentCategoryInternalCode": "7234",
    "weight": 2
}

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

Upsert subcategory

PUT/subcategory

This endpoint allows you to create or update an existing subcategory (upsert).

Request Body Parameters

Parameter	Type	Required	Descripción
name	string	Yes	Subcategory name
internalCode	string	Yes	Internal subcategory code
parentCategoryInternalCode	string	Yes	Internal code of the parent category
enabled	boolean	Yes	Subcategory enabled status
weight	integer	No	Value used for product positioning in listings (order of appearance)

Request Body Example

{
  "name": "Upsert Subcategory",
  "internalCode": "8765",
  "parentCategoryInternalCode": "7234",
  "enabled": true,
  "weight": 3
}

Response Codes

Code	Descripción
200	Successful operation - Subcategory updated
404	Not found - Subcategory not found

Example Usage

Javascript
Python

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

const data = {
  name: "Upsert Subcategory",
  internalCode: "8765",
  parentCategoryInternalCode: "7234",
  enabled: true,
  weight: 3,
};

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

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

data = {
    "name": "Upsert Subcategory",
    "internalCode": "8765",
    "parentCategoryInternalCode": "7234",
    "enabled": true,
    "weight": 3
}

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

Change subcategory status

PUT/subcategory/{code}/status

This endpoint allows you to enable or disable a subcategory.

Path Parameters

Parameter	Type	Required	Descripción
code	string	Yes	Subcategory code

Request Body Parameters

Parameter	Type	Required	Descripción
enabled	boolean	Yes	Enabled status (true/false)

Request Body Example

{
  "enabled": true
}

Response Codes

Code	Descripción
200	Successful operation - Status updated
404	Not found - Subcategory not found

Example Usage

Javascript
Python

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

const data = {
  enabled: true,
};

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

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

data = {
    "enabled": true
}

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

Response Types

Success Response

{
  "code": 200,
  "message": "Operation successful"
}

Error Response

{
  "code": 400,
  "message": "Invalid request parameters"
}

Best Practices

Consistent Naming: Use clear, descriptive names for categories and subcategories
Code Structure: Create a logical structure for internal codes to make them easily identifiable
Weight Management: Plan your weight values carefully to maintain desired ordering
Status Control: Use status changes instead of deleting categories
Parent References: Always verify parent category exists before creating subcategories
Image Management: Use high-quality images with public URLs - Nilo will optimize them for different devices

Common Use Cases

Initial Setup
- Create main categories for your product catalog
- Set up subcategories within each main category
- Configure weights for proper display order
Catalog Maintenance
- Update category names or images
- Enable/disable categories seasonally
- Adjust weights to change display order

Security

All API endpoints require two types of authentication:

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

Required Permissions

For category and subcategory endpoints, the following permissions are required:

For read operations: supplier/category.read
For write operations: supplier/category.write

Understanding Categories and Subcategories​

Important Considerations​

Single Operations​

Categories​

Get all categories​

Query Parameters​

Response Codes​

Example Usage​

Success Response Example​

Get a specific category​

Path Parameters​

Response Codes​

Example Usage​

Success Response Example​

Create a category​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Update a category​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Upsert category​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Change category status​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Subcategories​

Create a subcategory​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Update a subcategory​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Upsert subcategory​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Change subcategory status​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Response Types​

Success Response​

Error Response​

Best Practices​

Common Use Cases​

Security​

Required Permissions​

Understanding Categories and Subcategories

Important Considerations

Single Operations

Categories

Get all categories

Query Parameters

Response Codes

Example Usage

Success Response Example

Get a specific category

Path Parameters

Response Codes

Example Usage

Success Response Example

Create a category

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Update a category

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Upsert category

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Change category status

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Subcategories

Create a subcategory

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Update a subcategory

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Upsert subcategory

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Change subcategory status

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Response Types

Success Response

Error Response

Best Practices

Common Use Cases

Security

Required Permissions