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

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