Product Management API

The Product Management API allows you to manage product information in the Nilo platform. These endpoints help you create, update, and retrieve product data, including product details, images, and display configurations.

Understanding Products

Products in Nilo represent items available for sale across different stores:

Product Structure
- Unique internal code for identification (matches ERP)
- Name and description for display
- Brand and category associations
- Display configurations for different unit presentations
- Images (main and additional)
- Status for enabling/disabling visibility
Product Hierarchy
- Products belong to brands and categories
- Support multiple display configurations
- Maintain their own status and visibility
- Can be managed individually or in batches

Important Considerations

Unique Codes: Each product requires a unique internal code matching your ERP system
Display Configurations: Products can have multiple unit presentations (e.g., single unit, pack of 6)
Image Management: Products support a main image and additional images
Brand and Category: Products must be associated with valid brands and categories
Status Control: Products can be enabled or disabled without deletion

Single Product Operations

Create Product

POST/product

Create a new product in the Nilo platform. This endpoint is used to register all product details including:

Product information (name, description, codes)
Brand and category associations
Display configurations (units, default display)
Product images

Request Body Parameters

Parameter	Type	Required	Description
name	string	Yes	Product name
internalCode	string	Yes	Product code (same as in ERP)
description	string	Yes	Product description
brandInternalCode	string	Yes	Brand code (same as in ERP)
categoryInternalCode	string	Yes	Category code (same as in ERP)
displayProducts	array	Yes	Array of display configurations (see below)
mainImage	string	No	Public URL of main product image
images	array	No	Array of additional public image URLs
codeDUN	string	No	DUN code (same as in ERP)
codeUPC	string	No	UPC code (same as in ERP)
weight	integer	No	Order positioning in listings

Image Management

The mainImage and images fields expect public and accessible URLs. During processing, Nilo will download the images, store them on Nilo servers, and distribute them through a CDN for optimized loading. Use high-quality images - the platform will automatically generate optimized versions for different devices.

Display Product Configuration

Parameter	Type	Required	Description
default	boolean	Yes	Whether this is the default display
units	integer	Yes	Number of units in this display configuration
internalCode	string	No	Display-specific code
codeDUN	string	No	DUN code for this display (same as in ERP)
codeUPC	string	No	UPC code for this display (same as in ERP)

Request Body Example

{
  "name": "Bebida 1L",
  "internalCode": "12345",
  "description": "Bebida refrescante 1L",
  "brandInternalCode": "brand1",
  "categoryInternalCode": "category1",
  "displayProducts": [
    {
      "default": true,
      "units": 1,
      "internalCode": "12345.1"
    }
  ],
  "mainImage": "https://image.jpg",
  "images": ["https://image1.jpg"]
}

Response Codes

Code	Description
200	Product created successfully
400	Invalid request parameters
401	Unauthorized access

Example Usage

Javascript
Python

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

const data = {
  name: "Bebida 1L",
  internalCode: "12345",
  description: "Bebida refrescante 1L",
  brandInternalCode: "brand1",
  categoryInternalCode: "category1",
  displayProducts: [
    {
      default: true,
      units: 1,
      internalCode: "12345.1",
    },
  ],
  mainImage: "https://image.jpg",
  images: ["https://image1.jpg"],
};

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

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

data = {
    "name": "Bebida 1L",
    "internalCode": "12345",
    "description": "Bebida refrescante 1L",
    "brandInternalCode": "brand1",
    "categoryInternalCode": "category1",
    "displayProducts": [
        {
            "default": True,
            "units": 1,
            "internalCode": "12345.1"
        }
    ],
    "mainImage": "https://image.jpg",
    "images": ["https://image1.jpg"]
}

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

Get All Products

GET/product

Retrieve a paginated list of all products. This endpoint is useful for:

Browsing through the product catalog
Implementing pagination in your application
Filtering products by enabled status

Query Parameters

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

Response Example

{
  "data": [
    {
      "name": "Bebida 1L",
      "internalCode": "12345",
      "description": "Bebida refrescante 1L",
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "brand": {
        "name": "Marca 1",
        "internalCode": "brand1"
      },
      "category": {
        "name": "Bebidas",
        "internalCode": "category1"
      },
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ],
  "page": {
    "pageBased": {
      "count": 100
    },
    "cursorBased": {
      "hasNextPage": true,
      "hasPreviousPage": false,
      "firstCursor": "0",
      "lastCursor": "49"
    }
  }
}

Example Usage

Javascript
Python

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/product?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/product"
params = {
    "take": 10,
    "page": 1,
    "enabled": True
}

headers = {
    'Authorization': 'YOUR_AUTH_TOKEN',
    'x-api-key': 'YOUR_API_KEY'
}

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

Get Product Details

GET/product/{code}

Retrieve detailed information about a specific product. This endpoint returns:

Product metadata
Brand and category information
All display configurations
Product images

Path Parameters

Parameter	Type	Description
code	string	Product internal code (same as in ERP)

Response Example

{
  "name": "Bebida 1L",
  "internalCode": "12345",
  "description": "Bebida refrescante 1L",
  "mainImage": "https://image.jpg",
  "images": ["https://image1.jpg"],
  "brand": {
    "name": "Marca 1",
    "internalCode": "brand1"
  },
  "category": {
    "name": "Bebidas",
    "internalCode": "category1"
  },
  "displayProducts": [
    {
      "default": true,
      "units": 1,
      "internalCode": "12345.1"
    }
  ]
}

Example Usage

const headers = {
  Authorization: "YOUR_AUTH_TOKEN",
  "x-api-key": "YOUR_API_KEY",
};

fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/product/12345",
  {
    method: "GET",
    headers: headers,
  }
)
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Upsert Product

PUT/product

Create or update a product in the Nilo platform. This endpoint is useful when you need to:

Create a new product if it doesn't exist
Update an existing product with new information

Request Body Parameters

Parameter	Type	Required	Description
internalCode	string	Yes	Product code (same as in ERP)
name	string	Yes	Product name
description	string	Yes	Product description
brandInternalCode	string	Yes	Brand code (same as in ERP)
categoryInternalCode	string	Yes	Category code (same as in ERP)
displayProducts	array	Yes	Array of display configurations
enabled	boolean	Yes	Whether the product is active
mainImage	string	No	Public URL of main product image
images	array	No	Array of additional public image URLs
codeDUN	string	No	DUN code (same as in ERP)
codeUPC	string	No	UPC code (same as in ERP)
weight	integer	No	Order positioning in listings

Image Management

Request Body Example

{
  "internalCode": "12345",
  "name": "Bebida 1L",
  "description": "Bebida refrescante 1L",
  "brandInternalCode": "brand1",
  "categoryInternalCode": "category1",
  "enabled": true,
  "mainImage": "https://image.jpg",
  "images": ["https://image1.jpg"],
  "codeDUN": "codeDUN123",
  "codeUPC": "codeUPC123",
  "weight": 1,
  "displayProducts": [
    {
      "default": true,
      "units": 1,
      "internalCode": "12345.1"
    }
  ]
}

Response Codes

Code	Description
200	Product upserted successfully
404	Product not found

Example Usage

Javascript
Python

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

const data = {
  internalCode: "12345",
  name: "Bebida 1L",
  description: "Bebida refrescante 1L",
  brandInternalCode: "brand1",
  categoryInternalCode: "category1",
  enabled: true,
  mainImage: "https://image.jpg",
  images: ["https://image1.jpg"],
  displayProducts: [
    {
      default: true,
      units: 1,
      internalCode: "12345.1",
    },
  ],
};

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

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

data = {
    "internalCode": "12345",
    "name": "Bebida 1L",
    "description": "Bebida refrescante 1L",
    "brandInternalCode": "brand1",
    "categoryInternalCode": "category1",
    "enabled": True,
    "mainImage": "https://image.jpg",
    "images": ["https://image1.jpg"],
    "displayProducts": [
        {
            "default": True,
            "units": 1,
            "internalCode": "12345.1"
        }
    ]
}

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

Change Product Status

PUT/product/{code}/status

Update the status of a product or specific display. This endpoint allows you to:

Enable/disable a product
Update the status of specific display configurations
Manage product visibility in catalogs

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Product internal code (same as in ERP)

Request Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	Whether the product/display should be enabled
units	integer	No	Specific display units to update (if not provided, updates entire product)

Request Body Example

{
  "enabled": true,
  "units": 1
}

Response Codes

Code	Description
200	Status updated successfully
400	Invalid request parameters
404	Product not found

Example Usage

Javascript
Python

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

const data = {
  enabled: true,
  units: 1,
};

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

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

data = {
    "enabled": True,
    "units": 1
}

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

Batch Operations

Change Product Status in Batch

POST/batch/product/status

Enables or disables multiple products asynchronously. Each item requires code and enabled; units is optional. The response returns 202 Accepted with batchIds, which can be followed through the Batch Operations API.

{
  "items": [
    { "code": "PRODUCT-001", "enabled": true, "units": 100 },
    { "code": "PRODUCT-002", "enabled": false }
  ]
}

Required permission: supplier/product.bulkwrite.

Batch Product Operations

POST/batch/product

Perform bulk operations on products. This endpoint allows you to:

Create multiple new products
Update existing products
Upsert products (update or create if not exists)

The batch operation is processed asynchronously, meaning you'll receive an immediate acknowledgment of the request, and the updates will be processed in the background.

Image Management

Request Body Parameters

Parameter	Type	Description
create	array	Array of products to create
update	array	Array of products to update
upsert	array	Array of products to update or create if needed

Each product in the arrays supports the following fields: internalCode, name, description, brandInternalCode, categoryInternalCode, displayProducts, enabled, mainImage, images, codeDUN, codeUPC, weight.

Request Body Example

{
  "create": [
    {
      "name": "New Product",
      "internalCode": "67890",
      "description": "New product description",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "67890.1"
        }
      ]
    }
  ],
  "update": [
    {
      "internalCode": "12345",
      "name": "Updated Product Name",
      "description": "Updated description",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ],
  "upsert": [
    {
      "internalCode": "12345",
      "name": "Upserted Product Name",
      "description": "Upserted description",
      "brandInternalCode": "brand2",
      "categoryInternalCode": "category2",
      "enabled": true,
      "mainImage": "https://image.jpg",
      "images": ["https://image1.jpg"],
      "displayProducts": [
        {
          "default": true,
          "units": 1,
          "internalCode": "12345.1"
        }
      ]
    }
  ]
}

Response Codes

Code	Description
202	Batch request accepted for processing
400	Invalid request parameters
401	Unauthorized access

Example Usage

Javascript
Python

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

const data = {
  upsert: [
    {
      internalCode: "12345",
      name: "Upserted Product Name",
      description: "Upserted description",
      brandInternalCode: "brand2",
      categoryInternalCode: "category2",
      enabled: true,
      mainImage: "https://image.jpg",
      images: ["https://image1.jpg"],
      displayProducts: [
        {
          default: true,
          units: 1,
          internalCode: "12345.1",
        },
      ],
    },
  ],
};

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

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

data = {
    "upsert": [
        {
            "internalCode": "12345",
            "name": "Upserted Product Name",
            "description": "Upserted description",
            "brandInternalCode": "brand2",
            "categoryInternalCode": "category2",
            "enabled": True,
            "mainImage": "https://image.jpg",
            "images": ["https://image1.jpg"],
            "displayProducts": [
                {
                    "default": True,
                    "units": 1,
                    "internalCode": "12345.1"
                }
            ]
        }
    ]
}

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

Response Types

Success Response

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

Batch Operation Response

{
  "code": 202,
  "batchIds": {
    "create": ["550e8400-e29b-41d4-a716-446655440000"],
    "update": [],
    "upsert": []
  },
  "message": "Batch processing started"
}

Error Response

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

Best Practices

Product Management
- Use consistent naming conventions
- Maintain accurate product descriptions
- Keep brand and category associations updated
- Implement proper status management
Display Configuration
- Define clear unit presentations
- Set appropriate default displays
- Maintain consistent internal codes
- Document unit configurations
Image Handling
- Use high-quality images with public URLs
- Nilo will download and optimize images automatically
- Images are distributed through CDN for fast loading
- Platform generates optimized versions for different devices
Performance Optimization
- Use batch operations for multiple updates
- Implement proper caching strategies
- Optimize image delivery
- Monitor API usage patterns

Common Use Cases

Initial Product Setup
- Create basic product information
- Configure display units
- Upload product images
- Set brand and category associations
Product Maintenance
- Update product information
- Manage product visibility
- Update display configurations
- Refresh product images
Bulk Operations
- Import multiple products
- Update product statuses
- Modify display configurations
- Sync product data
Product Integration
- Connect with inventory systems
- Implement product search
- Configure product displays
- Set up product filtering

Implementation Guidelines

Product Creation
- Validate all required fields
- Check for duplicate codes
- Process product images
- Set default configurations
Product Updates
- Verify product existence
- Handle partial updates
- Manage image changes
- Update related entities
Display Management
- Handle unit configurations
- Update default displays
- Maintain display codes
- Validate unit values
Batch Processing
- Validate batch data
- Handle partial failures
- Implement rollback
- Report batch results

Security

All API endpoints require two types of authentication:

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

Required Permissions

For product management endpoints, the following permissions are required:

For read operations: supplier/product.read
For write operations: supplier/product.write
For bulk operations: supplier/product.bulkwrite

Error Codes

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

{
  "code": 404,
  "message": "PRODUCT_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "PRODUCT_NOT_FOUND",
    "message": "Product not found",
    "entity": "product",
    "entityCode": "PROD-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
`PRODUCT_NOT_FOUND`	The product does not exist for the given internal code

409 — Conflict

Error Code	Description
`PRODUCT_NAME_ALREADY_EXIST`	A product with the same name already exists
`PRODUCT_CODE_ALREADY_EXIST`	A product with the same internal code already exists

Error Handling

Input Validation
- Validate all required fields
- Check data types and formats
- Verify image specifications
- Validate internal codes
Error Responses
- Use appropriate HTTP status codes
- Provide detailed error messages
- Include field-level errors
- Add error tracking codes
Recovery Procedures
- Handle network failures
- Implement retry logic
- Maintain data consistency
- Log error details
Monitoring
- Track error rates
- Monitor API performance
- Alert on critical errors
- Analyze error patterns

Understanding Products​

Important Considerations​

Single Product Operations​

Create Product​

Request Body Parameters​

Display Product Configuration​

Request Body Example​

Response Codes​

Example Usage​

Get All Products​

Query Parameters​

Response Example​

Example Usage​

Get Product Details​

Path Parameters​

Response Example​

Example Usage​

Upsert Product​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Change Product Status​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Batch Operations​

Change Product Status in Batch​

Batch Product Operations​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Response Types​

Success Response​

Batch Operation Response​

Error Response​

Best Practices​

Common Use Cases​

Implementation Guidelines​

Security​

Required Permissions​

Error Codes​

404 — Not Found​

409 — Conflict​

Error Handling​

Tana

Understanding Products

Important Considerations

Single Product Operations

Create Product

Request Body Parameters

Display Product Configuration

Request Body Example

Response Codes

Example Usage

Get All Products

Query Parameters

Response Example

Example Usage

Get Product Details

Path Parameters

Response Example

Example Usage

Upsert Product

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Change Product Status

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Batch Operations

Change Product Status in Batch

Batch Product Operations

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Response Types

Success Response

Batch Operation Response

Error Response

Best Practices

Common Use Cases

Implementation Guidelines

Security

Required Permissions

Error Codes

404 — Not Found

409 — Conflict

Error Handling