Stock Management API

The Stock Management API allows you to manage product availability using stock groupers. These endpoints help you maintain accurate stock information in the Nilo platform.

Understanding Stock Management

Stock management in Nilo is organized around groupers - logical groups of stores that share the same product availability:

• Stock Structure

  • Product availability is managed per grouper (not per individual store)
  • Unit-specific availability tracking for display configurations
  • Grouper-based management enables efficient updates across multiple stores
  • Status tracking for product availability

• Stock Hierarchy

  • Stores are assigned to stock groupers
  • Products are marked as available/unavailable for a grouper
  • All stores in a grouper share the same product availability
  • Support for batch operations across multiple products

Important Considerations

1. Grouper-Based Management: Stock is managed at the grouper level, not individual stores
2. Unit Management: Stock can be managed at the unit presentation level (display configurations)
3. Grouper System: Create groupers to represent warehouses, regions, or distribution centers
4. Batch Operations: Support for bulk updates across multiple products
5. Real-time Updates: Stock changes affect immediate product visibility in all stores of the grouper

Single Product Operations

Update Product Stock

POST/product/{code}/stock

This endpoint allows you to update the availability status of a specific product for a particular stock grouper. Use this when you need to:

• Mark a product as available/unavailable for a specific grouper
• Update the available units for a specific product display
• Manage individual product visibility across all stores in a grouper

When a product is marked as unavailable, it won't be displayed in the catalogs of any store belonging to that grouper, preventing customers from ordering out-of-stock items.

Path Parameters

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

Request Body Parameters

Parameter	Type	Required	Description
grouperCode	string	Yes	The stock grouper code where availability is being updated (same as in the ERP)
available	boolean	Yes	Whether the product is available (true) or unavailable (false) for the grouper
units	integer	No	Number of units. When specified, only updates the display with this specific unit configuration

Request Body Example

{
  "grouperCode": "123456",
  "available": true,
  "units": 1
}

Response Codes

Code	Description
200	Successful operation
404	Product Code not found or Grouper code not found

Example Usage

Javascript

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

const data = {
  grouperCode: "123456",
  available: true,
  units: 1,
};

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

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

data = {
    "grouperCode": "123456",
    "available": True,
    "units": 1
}

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

Batch Operations

Batch Update Stock by Grouper

POST/batch/stock/grouper

This endpoint allows you to update product availability for multiple products at once using grouper codes. This is the main endpoint for daily stock management.

Use this endpoint when you need to:

• Update stock status for multiple products simultaneously
• Synchronize inventory data from your ERP system
• Perform bulk availability updates for a specific grouper
• Efficiently manage product visibility across all stores in a grouper

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.

Recommended for Daily Operations

This is the most efficient method for daily stock management. Instead of updating products one by one, send batches of availability updates for a specific grouper.

Request Body Parameters

Parameter	Type	Required	Description
productCode	string	Yes	Product internal code (same as in ERP)
grouperCode	string	Yes	Stock grouper code - all stores in this grouper will be affected
available	boolean	Yes	Whether the product is available (true) or unavailable (false)

Request Body Example

{
  "availability": [
    {
      "productCode": "22222",
      "grouperCode": "123456",
      "available": true
    },
    {
      "productCode": "33333",
      "grouperCode": "123456",
      "available": false
    },
    {
      "productCode": "44444",
      "grouperCode": "789012",
      "available": true
    }
  ]
}

Response Codes

Code	Description
200	Request accepted, processing initiated
404	Grouper Code not found

Example Usage

Javascript

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

const data = {
  availability: [
    {
      productCode: "22222",
      grouperCode: "123456",
      available: true,
    },
    {
      productCode: "33333",
      grouperCode: "123456",
      available: false,
    },
  ],
};

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

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

data = {
    "availability": [
        {
            "productCode": "22222",
            "grouperCode": "123456",
            "available": True
        },
        {
            "productCode": "33333",
            "grouperCode": "123456",
            "available": False
        }
    ]
}

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

Response Types

Success Response

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

Batch Operation Response

{
  "code": 201,
  "batchIds": [
    {
      "code": "12356",
      "uuid": ["550e8400-e29b-41d4-a716-446655440000"]
    }
  ],
  "message": "Operation in processing"
}

Error Response

{
  "code": 404,
  "message": "Product Code not found"
}

Best Practices

1. Grouper-Based Management

   • Create groupers that represent your warehouses or distribution centers
   • Assign stores to groupers based on which warehouse supplies them
   • Use batch operations for efficient daily stock updates
   • Keep grouper assignments up to date

2. Stock Updates

   • Use /batch/stock/grouper for bulk daily updates
   • Use /product/{code}/stock for individual product updates
   • Send available: true or available: false based on actual inventory
   • Update only when stock status changes to minimize API calls

3. Batch Processing

   • Group updates by grouperCode for efficiency
   • Send multiple products in a single batch request
   • Monitor batch processing status using the batch status endpoints
   • Handle partial failures gracefully

4. Performance Optimization

   • Use batch operations instead of individual updates when possible
   • Schedule bulk updates during off-peak hours
   • Monitor API usage patterns
   • Implement retry logic for failed requests

Common Use Cases

1. Initial Stock Setup

   • Create stock groupers for each warehouse/depot
   • Assign stores to their corresponding groupers
   • Initialize product availability for each grouper
   • Configure unit presentations if needed

2. Daily Stock Sync

   • Export availability data from your ERP
   • Send batch updates using /batch/stock/grouper
   • Update products that changed status
   • Monitor batch processing results

3. Individual Product Updates

   • Use /product/{code}/stock for real-time updates
   • Update specific display units if needed
   • React to immediate stock changes
   • Handle out-of-stock situations quickly

4. Integration Scenarios

   • Connect with ERP/WMS systems
   • Implement scheduled inventory sync
   • Set up webhooks for stock alerts
   • Configure automated availability rules

Implementation Guidelines

1. Availability Management

   • Validate grouperCode exists before updating
   • Check product existence
   • Handle unit configurations for specific displays
   • Use batch status endpoints to monitor updates

2. Grouper Setup

   • Create stock groupers using /grouper/stock endpoint
   • Assign stores to groupers when creating/updating stores
   • Use meaningful grouperCodes that match your ERP
   • Document grouper-warehouse relationships

3. Stock Synchronization

   • Schedule regular sync from your inventory system
   • Use batch endpoint for bulk updates
   • Track which products changed since last sync
   • Handle errors and retry failed updates

4. Batch Processing

   • Validate batch data before sending
   • Handle partial failures gracefully
   • Use batch status endpoint to check results
   • Implement logging for audit purposes

Security

All API endpoints require two types of authentication:

1. API Key in header: x-api-key
2. Authorization token in header: Authorization

Required Permissions

For stock 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 Handling

1. Input Validation

   • Validate store codes
   • Check product codes
   • Verify unit values
   • Validate grouper codes

2. Error Responses

   • Use appropriate HTTP status codes
   • Provide detailed error messages
   • Include field-level errors
   • Add error tracking codes

3. Recovery Procedures

   • Handle network failures
   • Implement retry logic
   • Maintain data consistency
   • Log error details

4. Monitoring

   • Track error rates
   • Monitor API performance
   • Alert on critical errors
   • Analyze error patterns