Orders Management API

The Orders Management API allows you to manage and track orders in the Nilo platform. These endpoints help you retrieve, confirm, deliver, return, and cancel orders, as well as perform batch operations and import order history.

Understanding Orders

Orders in Nilo represent customer purchases:

Order Structure
- Unique order identifier
- Customer and delivery information
- List of products and quantities
- Order status (PENDING, CONFIRMED, DELIVERED, CANCELLED)
- Creation, confirmation, and delivery dates
- Billing and shipping details
Order Hierarchy
- Orders contain multiple items
- Each item is associated with a product
- Orders go through different states
- Support for partial deliveries and returns
- Maintain change history

Important Considerations

Order States: Orders can be in different states (PENDING, CONFIRMED, DELIVERED, CANCELLED)
State Flow: Normal flow is PENDING → CONFIRMED → DELIVERED
Partial Deliveries: Orders can be delivered partially with specific products
Returns: Products can be returned after delivery
Cancellations: An order can be cancelled with specific reason codes
Batch Operations: Support for efficiently updating multiple orders

Single Order Operations

Get Order by ID

GET/order/{id}

Retrieves the details of a specific order. This endpoint is useful for:

Checking current order status
Getting complete ordered product details
Retrieving delivery and billing information

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Order identification code (same as informed in the webhook)

Response Codes

Code	Description
200	Successful operation
404	Order not found

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/order/1234567890",
  {
    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/order/1234567890"

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

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

List All Orders

GET/order

Retrieves a paginated list of orders with filtering options. This endpoint allows:

Querying orders by status
Filtering by date range
Implementing cursor-based pagination
Monitoring pending orders

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)
cursor	string	No	Cursor for pagination. First call should pass 0, subsequent calls should use the cursor from the last item of the previous response
status	string	No	Order status (DELIVERED, PENDING, CONFIRMED, CANCELLED)
from	string	No	Start date to filter orders (YYYY-MM-DD format, required if 'to' is specified)
to	string	No	End date to filter orders (YYYY-MM-DD format, required if 'from' is specified)

Example Usage

Javascript
Python

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

// First request
fetch(
  "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/order?status=PENDING&take=50&cursor=0",
  {
    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/order"

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

params = {
    'status': 'PENDING',
    'take': 50,
    'cursor': 0
}

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

Confirm Order

PUT/order/{id}/confirm

Confirms an order and sets the estimated delivery date. This endpoint allows:

Accepting an order for processing
Setting estimated delivery date
Updating delivery date in subsequent confirmations

If the order has already been confirmed, subsequent requests will update the delivery date with the latest provided date.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Order identification code (same as informed in the webhook)

Request Body Parameters

Parameter	Type	Required	Description
deliveryDate	string	No	Estimated delivery date (YYYY-MM-DD format)

Request Body Example

{
  "deliveryDate": "2025-12-03"
}

Response Codes

Code	Description
200	Successful operation
404	Order not found

Example Usage

Javascript
Python

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

const data = {
  deliveryDate: "2025-12-03",
};

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

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

data = {
    "deliveryDate": "2025-12-03"
}

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

Mark Order as Delivered

PUT/order/{id}/deliver

Updates an order's status to delivered. This endpoint supports both complete and partial deliveries.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Order identification code (same as informed in the webhook)

Request Body Parameters

Parameter	Type	Required	Description
complete	boolean	No	Whether the order was completely delivered
partialDelivery	object	No	Partial delivery information (if order is partially delivered)

partialDelivery object:

Parameter	Type	Required	Description
date	string	Yes	Delivery date (YYYY-MM-DD format)
products	array	Yes	List of products that were delivered

products array items:

Parameter	Type	Required	Description
productCode	string	Yes	Product internal code
units	integer	Yes	Units per package
quantity	number	Yes	Quantity delivered

Request Body Example - Complete Delivery

{
  "complete": true
}

Request Body Example - Partial Delivery

{
  "complete": false,
  "partialDelivery": {
    "date": "2025-12-03",
    "products": [
      {
        "productCode": "12345",
        "units": 1,
        "quantity": 5
      },
      {
        "productCode": "67890",
        "units": 6,
        "quantity": 2
      }
    ]
  }
}

Response Codes

Code	Description
200	Successful operation
404	Order not found

Return Order Products

PUT/order/{id}/return

Returns products from a delivered order. Use this endpoint to register product returns.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Order identification code (same as informed in the webhook)

Request Body Parameters

Parameter	Type	Required	Description
date	string	Yes	Return date (YYYY-MM-DD format)
products	array	Yes	List of products being returned

products array items:

Parameter	Type	Required	Description
productCode	string	Yes	Product internal code
units	integer	Yes	Units per package
quantity	number	Yes	Quantity being returned

Request Body Example

{
  "date": "2025-12-03",
  "products": [
    {
      "productCode": "12345",
      "units": 1,
      "quantity": 2
    }
  ]
}

Response Codes

Code	Description
200	Successful operation
404	Order not found

Example Usage

Javascript
Python

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

const data = {
  date: "2025-12-03",
  products: [
    {
      productCode: "12345",
      units: 1,
      quantity: 2,
    },
  ],
};

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

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

data = {
    "date": "2025-12-03",
    "products": [
        {
            "productCode": "12345",
            "units": 1,
            "quantity": 2
        }
    ]
}

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

Cancel Order

PUT/order/{id}/cancel

Cancels an existing order. You must provide a cancellation reason code.

Path Parameters

Parameter	Type	Required	Description
id	integer	Yes	Order identification code (same as informed in the webhook)

Request Body Parameters

Parameter	Type	Required	Description
code	string	No	Cancellation reason code

Cancellation Reason Codes

Code	Description
IMPRECISE_DELIVERY_ADDRESS	Delivery address is imprecise
OUT_DELIVERY_HOURS	Outside delivery hours
OUT_TIME_CONFIRM	Confirmation time expired
OUTSTANDING_BALANCE	Customer has outstanding balance
OUT_OF_STOCK	Products are out of stock
OTHER	Other reason

Request Body Example

{
  "code": "OUT_OF_STOCK"
}

Response Codes

Code	Description
200	Successful operation
404	Order not found

Example Usage

Javascript
Python

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

const data = {
  code: "OUT_OF_STOCK",
};

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

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

data = {
    "code": "OUT_OF_STOCK"
}

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

Batch Operations

Batch Order Updates

POST/batch/order

Performs updates on multiple orders simultaneously. This endpoint allows you to confirm, deliver, return, or cancel multiple orders in a single request.

Request Body Structure

The request body contains a status object with arrays for each operation type:

{
  "status": {
    "confirm": [...],
    "deliver": [...],
    "return": [...],
    "cancel": [...]
  }
}

Confirm Array Items

Parameter	Type	Required	Description
id	integer	Yes	Order identification
deliveryDate	string	No	Estimated delivery date (YYYY-MM-DD)

Deliver Array Items

Parameter	Type	Required	Description
id	integer	Yes	Order identification
complete	boolean	No	Whether the order was completely delivered
partialDelivery	object	No	Partial delivery info (date + products array)

Return Array Items

Parameter	Type	Required	Description
id	integer	Yes	Order identification
date	string	Yes	Return date (YYYY-MM-DD)
products	array	Yes	List of products being returned

Cancel Array Items

Parameter	Type	Required	Description
id	integer	Yes	Order identification
code	string	No	Reason code: IMPRECISE_DELIVERY_ADDRESS, OUT_DELIVERY_HOURS, OUT_TIME_CONFIRM, OUTSTANDING_BALANCE, OUT_OF_STOCK, OTHER

Request Body Example

{
  "status": {
    "confirm": [
      {
        "id": 10,
        "deliveryDate": "2025-12-03"
      },
      {
        "id": 11,
        "deliveryDate": "2025-12-04"
      }
    ],
    "deliver": [
      {
        "id": 5,
        "complete": true
      },
      {
        "id": 6,
        "complete": false,
        "partialDelivery": {
          "date": "2025-12-03",
          "products": [
            {
              "productCode": "12345",
              "units": 1,
              "quantity": 5
            }
          ]
        }
      }
    ],
    "cancel": [
      {
        "id": 7,
        "code": "OUT_OF_STOCK"
      }
    ]
  }
}

Response Codes

Code	Description
202	Request accepted, processing initiated
402	Bad request

Example Usage

Javascript
Python

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

const data = {
  status: {
    confirm: [
      { id: 10, deliveryDate: "2025-12-03" },
      { id: 11, deliveryDate: "2025-12-04" },
    ],
    deliver: [{ id: 5, complete: true }],
    cancel: [{ id: 7, code: "OUT_OF_STOCK" }],
  },
};

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

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

data = {
    "status": {
        "confirm": [
            {"id": 10, "deliveryDate": "2025-12-03"},
            {"id": 11, "deliveryDate": "2025-12-04"}
        ],
        "deliver": [
            {"id": 5, "complete": True}
        ],
        "cancel": [
            {"id": 7, "code": "OUT_OF_STOCK"}
        ]
    }
}

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

Import Operations

Bulk Import Orders

POST/order/bulk-import

Allows you to import order history from other systems (e.g., your ERP). This is useful for:

Migrating historical orders to Nilo
Synchronizing orders created in other systems
Maintaining a complete order history

Request Body Parameters

Parameter	Type	Required	Description
orders	array	Yes	Array of orders to import

Order object:

Parameter	Type	Required	Description
id	integer	Yes	Order identification
source	string	Yes	Source system identifier (e.g., "ERP")
buyer	object	Yes	Buyer information (storeCode, routeCode)
address	object	Yes	Delivery address (addressLine, zipCode, etc.)
status	string	Yes	Order status: PENDING, CONFIRMED, CANCELLED, DELIVERED
createdAt	string	Yes	Creation date (YYYY-MM-DD)
products	array	No	List of products in the order
invoices	array	No	List of invoices generated from the order

Request Body Example

{
  "orders": [
    {
      "id": 10,
      "source": "ERP",
      "buyer": {
        "storeCode": "10",
        "routeCode": "10"
      },
      "address": {
        "addressLine": "25 de mayo 1200, Buenos Aires, Argentina",
        "zipCode": "2400"
      },
      "status": "DELIVERED",
      "createdAt": "2025-12-03",
      "products": [
        {
          "productCode": "12345",
          "units": 1,
          "quantity": 5
        }
      ]
    }
  ]
}

Response Codes

Code	Description
200	Orders received successfully
400	Error in request validation
500	Internal server error

Quick Order

POST/order/quick-order

Allows other systems to send quick order suggestions to users. This endpoint is useful for:

Suggesting products to users based on their purchase history
Creating pre-populated shopping lists
Enabling one-click reorder functionality

Request Body Parameters

The request body is an array of product suggestions:

Parameter	Type	Required	Description
productInternalCode	string	Yes	Product identification code (same as in ERP)
units	integer	No	Units to search for specific display
quantity	integer	No	Quantity of products to suggest
rank	integer	No	Rank/order of the product in the suggestion list
displayInGroup	array	No	Alternative displays to show to the user

Request Body Example

[
  {
    "productInternalCode": "529",
    "units": 1,
    "quantity": 4,
    "rank": 1
  },
  {
    "productInternalCode": "530",
    "units": 6,
    "quantity": 2,
    "rank": 2,
    "displayInGroup": [
      {
        "productInternalCode": "530",
        "units": 1
      }
    ]
  }
]

Response Codes

Code	Description
200	Orders received successfully
400	Error in request validation
500	Internal server error

Response Types

Success Response

{
  "code": 200,
  "message": "Operation successful",
  "data": {
    "id": "22",
    "status": "CONFIRMED",
    "estimatedDeliveryDate": "2024-02-20",
    "items": [
      {
        "productCode": "123",
        "quantity": 2
      }
    ]
  }
}

Error Response Examples

Order Not Found

{
  "code": 404,
  "message": "Order not found"
}

Validation Error

{
  "code": 400,
  "message": "Invalid data",
  "errors": [
    {
      "field": "estimatedDeliveryDate",
      "message": "Delivery date is required"
    }
  ]
}

Best Practices

State Management
- Respect order state flow: PENDING → CONFIRMED → DELIVERED
- Use appropriate cancellation codes when cancelling orders
- Track partial deliveries and returns accurately
- Maintain date consistency across operations
Date Handling
- Use YYYY-MM-DD format for all dates
- Validate realistic delivery dates
- Consider time zones
- Maintain change history
Order Processing
- Implement inventory validations before confirming
- Use partial delivery when not all products are delivered
- Track returns properly for inventory management
- Document cancellation reasons with appropriate codes
Performance Optimization
- Use batch operations for mass updates
- Use cursor-based pagination for listing orders
- Implement caching when appropriate
- Monitor response times

Common Use Cases

New Order Management
- Monitor pending orders using the list endpoint with status filter
- Confirm orders quickly with estimated delivery dates
- Validate product availability before confirming
- Use webhooks to receive new order notifications
Delivery Management
- Mark orders as delivered (complete or partial)
- Track partial deliveries with specific products
- Handle returns when products are sent back
- Document delivery issues
Batch Operations
- Confirm multiple orders at once
- Process batch deliveries at end of day
- Handle batch cancellations
- Synchronize order states with your ERP
Order Import
- Import historical orders from your ERP
- Sync orders created in other systems
- Use quick-order for suggested purchases
- Maintain complete order history in Nilo

Implementation Guidelines

Order Processing
- Validate required data before operations
- Verify current state allows the transition
- Use batch endpoint for multiple updates
- Handle errors gracefully
State Management
- Implement state machine logic
- Validate transitions are allowed
- Record changes with timestamps
- Notify relevant systems of updates
Partial Operations
- Use partial delivery when not all products are delivered
- Track returned products with date and quantities
- Maintain accurate inventory based on deliveries/returns
- Handle exceptions appropriately
Batch Processing
- Validate batch data before sending
- Handle partial failures gracefully
- Check batch status for results
- Implement retry logic for failed items

Security

All API endpoints require two types of authentication:

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

Required Permissions

For order endpoints, the following permissions are required:

For read operations: supplier/order.read
For write operations: supplier/order.write
For batch and import operations: supplier/order.bulkwrite

Error Handling

Input Validation
- Validate order IDs
- Verify valid states
- Validate delivery dates
- Verify item data
Error Responses
- Use appropriate HTTP codes
- Provide clear messages
- Include specific details
- Maintain consistency
Recovery Procedures
- Handle network failures
- Implement retries
- Maintain data consistency
- Log critical errors
Monitoring
- Track error rates
- Monitor process times
- Alert on critical failures
- Analyze error patterns

Understanding Orders​

Important Considerations​

Single Order Operations​

Get Order by ID​

Path Parameters​

Response Codes​

Example Usage​

List All Orders​

Query Parameters​

Example Usage​

Confirm Order​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Mark Order as Delivered​

Path Parameters​

Request Body Parameters​

Request Body Example - Complete Delivery​

Request Body Example - Partial Delivery​

Response Codes​

Return Order Products​

Path Parameters​

Request Body Parameters​

Request Body Example​

Response Codes​

Example Usage​

Cancel Order​

Path Parameters​

Request Body Parameters​

Cancellation Reason Codes​

Request Body Example​

Response Codes​

Example Usage​

Batch Operations​

Batch Order Updates​

Request Body Structure​

Confirm Array Items​

Deliver Array Items​

Return Array Items​

Cancel Array Items​

Request Body Example​

Response Codes​

Example Usage​

Import Operations​

Bulk Import Orders​

Request Body Parameters​

Request Body Example​

Response Codes​

Quick Order​

Request Body Parameters​

Request Body Example​

Response Codes​

Response Types​

Success Response​

Error Response Examples​

Order Not Found​

Validation Error​

Best Practices​

Common Use Cases​

Implementation Guidelines​

Security​

Required Permissions​

Error Handling​

Understanding Orders

Important Considerations

Single Order Operations

Get Order by ID

Path Parameters

Response Codes

Example Usage

List All Orders

Query Parameters

Example Usage

Confirm Order

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Mark Order as Delivered

Path Parameters

Request Body Parameters

Request Body Example - Complete Delivery

Request Body Example - Partial Delivery

Response Codes

Return Order Products

Path Parameters

Request Body Parameters

Request Body Example

Response Codes

Example Usage

Cancel Order

Path Parameters

Request Body Parameters

Cancellation Reason Codes

Request Body Example

Response Codes

Example Usage

Batch Operations

Batch Order Updates

Request Body Structure

Confirm Array Items

Deliver Array Items

Return Array Items

Cancel Array Items

Request Body Example

Response Codes

Example Usage

Import Operations

Bulk Import Orders

Request Body Parameters

Request Body Example

Response Codes

Quick Order

Request Body Parameters

Request Body Example

Response Codes

Response Types

Success Response

Error Response Examples

Order Not Found

Validation Error

Best Practices

Common Use Cases

Implementation Guidelines

Security

Required Permissions

Error Handling