Price List Management API

Overview

The Price List Management API provides a comprehensive set of endpoints for managing price lists in the Nilo platform. This API allows you to create, update, and manage price lists for products across different stores, enabling flexible pricing strategies and efficient price management.

Understanding Price Lists

Price List Structure

• Internal Code: Unique identifier for the price list
• Name: Descriptive name for the price list
• Status: Enabled/disabled state of the price list
• Products: List of products with their specific prices and units
• Stores: List of stores associated with the price list

Important Considerations

• Each price list can have multiple products with different prices
• Products can have different prices based on units (package sizes)
• Price lists can be assigned to multiple stores
• Price lists can be enabled or disabled as needed
• Batch operations are available for efficient price management

Single Price List Operations

Create a Price List

POST/pricelist

Create a new price list with basic information.

Request Body Parameters

Parameter	Type	Required	Description
internalCode	string	Yes	Unique identifier for the price list
name	string	No	Descriptive name for the price list

Request Body Example

{
  "internalCode": "7634",
  "name": "price list food"
}

Response Codes

Code	Description
200	Price list created successfully
404	Price list already exists

Example Usage

Javascript

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

const data = {
  internalCode: "7634",
  name: "price list food",
};

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

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

data = {
    "internalCode": "7634",
    "name": "price list food"
}

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

Get Price List Details

GET/pricelist/{code}

Retrieve detailed information about a specific price list.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the price list

Response Example

{
  "internalCode": "7634",
  "name": "price list found",
  "enabled": true,
  "products": [
    {
      "priceListInternalCode": "124f",
      "productInternalCode": "22222.1",
      "units": 3,
      "price": 700.2
    }
  ],
  "stores": [
    {
      "priceListInternalCode": "124f",
      "storeInternalCode": "2345"
    }
  ]
}

Example Usage

Javascript

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

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

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

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

Change Price List Status

PUT/pricelist/{code}/status

Enable or disable a price list.

Path Parameters

Parameter	Type	Required	Description
code	string	Yes	Internal code of the price list

Request Body Parameters

Parameter	Type	Required	Description
enabled	boolean	Yes	Whether the price list should be enabled

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://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634/status",
  {
    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://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/pricelist/7634/status"

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 Price List

POST/batch/pricelist

Update multiple price lists, products, and store associations in a single operation.

Request Body Parameters

Parameter	Type	Required	Description
upsert	object	No	Contains products and stores to add/update
remove	object	No	Contains products and stores to remove

Request Body Example

{
  "upsert": {
    "products": [
      {
        "priceListInternalCode": "124f",
        "productInternalCode": "22222.1",
        "units": 3,
        "price": 700.2
      }
    ],
    "stores": [
      {
        "priceListInternalCode": "124f",
        "storeInternalCode": "2345"
      }
    ]
  },
  "remove": {
    "products": [],
    "stores": []
  }
}

Example Usage

Javascript

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

const data = {
  upsert: {
    products: [
      {
        priceListInternalCode: "124f",
        productInternalCode: "22222.1",
        units: 3,
        price: 700.2,
      },
    ],
    stores: [
      {
        priceListInternalCode: "124f",
        storeInternalCode: "2345",
      },
    ],
  },
  remove: {
    products: [],
    stores: [],
  },
};

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

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

data = {
    "upsert": {
        "products": [
            {
                "priceListInternalCode": "124f",
                "productInternalCode": "22222.1",
                "units": 3,
                "price": 700.2
            }
        ],
        "stores": [
            {
                "priceListInternalCode": "124f",
                "storeInternalCode": "2345"
            }
        ]
    },
    "remove": {
        "products": [],
        "stores": []
    }
}

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

Best Practices

1. Price List Organization

   • Create meaningful names for price lists
   • Group related products in the same price list
   • Maintain consistent pricing strategies across stores

2. Price Management

   • Regularly review and update prices
   • Use batch operations for bulk updates
   • Keep track of price list versions and changes

3. Store Association

   • Assign price lists to appropriate store groups
   • Verify store-price list relationships
   • Monitor price list effectiveness per store

4. Performance Optimization

   • Use batch operations for multiple updates
   • Implement proper error handling
   • Monitor API response times

Common Use Cases

1. Initial Price List Setup

   • Creating base price lists
   • Assigning stores to price lists
   • Setting up product prices

2. Price Updates

   • Updating prices for specific products
   • Modifying unit-based pricing
   • Batch price updates

3. Store Management

   • Adding stores to price lists
   • Removing stores from price lists
   • Managing store groups

4. Integration Scenarios

   • Synchronizing with external systems
   • Importing price data
   • Exporting price information

Implementation Guidelines

Creating a New Price List

1. Generate a unique internal code
2. Provide a descriptive name
3. Define initial product prices
4. Associate relevant stores
5. Enable the price list

Managing Products in Price Lists

1. Identify target products
2. Set appropriate unit prices
3. Update prices in batch when needed
4. Verify price updates

Store Operations

1. Identify target stores
2. Associate stores with price lists
3. Verify store-price list relationships
4. Monitor price effectiveness

Batch Processing

1. Prepare data in correct format
2. Use appropriate batch endpoints
3. Handle responses and errors
4. Verify successful updates

Error Codes

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

{
  "code": 404,
  "message": "PRICE_LIST_NOT_FOUND",
  "object": {
    "statusCode": 404,
    "code": "PRICE_LIST_NOT_FOUND",
    "message": "Price list not found",
    "entity": "priceList",
    "entityCode": "PL-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
PRICE_LIST_NOT_FOUND	The price list does not exist
PRICE_LIST_CODE_NOT_FOUND	The provided internal code does not match any existing price list

409 — Conflict

Error Code	Description
PRICE_LIST_ALREADY_EXIST	A price list with the same name already exists
PRICE_LIST_INTERNAL_CODE_ALREADY_EXIST	A price list with the same internal code already exists
PRODUCT_ALREADY_IN_PRICE_LIST	The product is already associated to this price list

Security

Authentication

• API Key required for all endpoints
• Authorization token needed for operations
• Proper scopes required for different operations

Required Permissions

• supplier/pricelist.read: For reading price list data
• supplier/pricelist.write: For creating and updating price lists
• supplier/pricelist.bulkwrite: For batch operations

Error Handling

Input Validation

• Verify required fields
• Validate price formats
• Check internal codes
• Ensure proper relationships

Error Responses

• 200: Successful operation
• 202: Batch process accepted
• 404: Price list not found
• 402: Bad request in batch operations

Recovery Procedures

1. Log error details
2. Implement retry mechanisms
3. Handle partial updates
4. Maintain data consistency

Monitoring

• Track API response times
• Monitor batch process status
• Log error frequencies
• Alert on critical failures

Batch Upsert Price Lists

POST/batch/pricelist/upsert

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

Use this endpoint when you need to:

• Synchronize your price list structure from your ERP system
• Create or update multiple price lists simultaneously
• Perform bulk imports of price list configurations

Difference from /batch/pricelist

The /batch/pricelist endpoint handles full price list data including products and prices. The /batch/pricelist/upsert endpoint is specifically for upserting the price list entities themselves (creating/updating the containers, not the individual prices within them).

Request Body Parameters

Parameter	Type	Required	Description
upsert	array	Yes	Array of price list objects
upsert[].internalCode	string	Yes	Unique price list code (same as in ERP)
upsert[].name	string	No	Price list display name
upsert[].enabled	boolean	Yes	Whether the price list is active

Request Body Example

{
  "upsert": [
    {
      "internalCode": "PRICELIST-001",
      "name": "Retail Standard",
      "enabled": true
    },
    {
      "internalCode": "PRICELIST-002",
      "name": "Wholesale Premium",
      "enabled": true
    },
    {
      "internalCode": "PRICELIST-003",
      "name": "Seasonal Promo",
      "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: [
    {
      internalCode: "PRICELIST-001",
      name: "Retail Standard",
      enabled: true,
    },
    {
      internalCode: "PRICELIST-002",
      name: "Wholesale Premium",
      enabled: true,
    },
  ],
};

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

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

data = {
    "upsert": [
        {
            "internalCode": "PRICELIST-001",
            "name": "Retail Standard",
            "enabled": True
        },
        {
            "internalCode": "PRICELIST-002",
            "name": "Wholesale Premium",
            "enabled": True
        }
    ]
}

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