Price Lists

Overview

Price Lists allow you to define custom pricing for specific products and assign those prices to customers. This is useful for:

Wholesale pricing
VIP customer discounts
Volume-based pricing tiers
Special promotions

How Price Lists Work

Create a price list (e.g., “Wholesale Prices”)
Assign products with fixed prices to the list
Assign customers to the price list
When selling to those customers, the POS uses the price list price instead of the base price

Create Price List

Creates a new empty price list.

Request Body

name

string

required

Price list name

description

string

Optional description of the price list purpose

Response

integer

Unique price list identifier

name

string

Price list name

description

string

Price list description

Example

curl -X POST "https://api.example.com/price-lists/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wholesale Prices",
    "description": "Special pricing for wholesale customers"
  }'

List Price Lists

Returns all price lists for the tenant, ordered by name.

Response

Returns an array of price list objects.

Example

curl -X GET "https://api.example.com/price-lists/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Price List Detail

Returns a price list with all its product price assignments.

Path Parameters

price_list_id

integer

required

The price list ID

Response

integer

Price list identifier

name

string

Price list name

description

string

Price list description

items

array

Array of product price assignments

items[].product_id

integer

Product ID

items[].fixed_price

decimal

Fixed price for this product in this list

Example

curl -X GET "https://api.example.com/price-lists/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Example

{
  "id": 1,
  "name": "Wholesale Prices",
  "description": "Special pricing for wholesale customers",
  "items": [
    {
      "product_id": 5,
      "fixed_price": 45000
    },
    {
      "product_id": 12,
      "fixed_price": 32000
    }
  ]
}

Update Price List

Updates the name and/or description of a price list.

Path Parameters

price_list_id

integer

required

The price list ID to update

Request Body

name

string

Updated name

description

string

Updated description

Example

curl -X PUT "https://api.example.com/price-lists/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Wholesale Prices",
    "description": "Updated pricing for premium wholesale customers"
  }'

Delete Price List

Deletes a price list. Customers assigned to this list will have their price_list_id set to NULL.

Path Parameters

price_list_id

integer

required

The price list ID to delete

Response

Returns 204 No Content on success.

Example

curl -X DELETE "https://api.example.com/price-lists/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

Assign Products to Price List

Replaces all product price assignments for a price list. This uses a clear-and-reinsert pattern, making it easy to bulk update prices from the frontend.

Path Parameters

price_list_id

integer

required

The price list ID

Request Body

items

array

required

Array of product price assignments

items[].product_id

integer

required

Product ID to assign

items[].fixed_price

decimal

required

Fixed price for this product

Response

Returns the updated price list with all items.

Example

curl -X PUT "https://api.example.com/price-lists/1/products" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "product_id": 5,
        "fixed_price": 45000
      },
      {
        "product_id": 12,
        "fixed_price": 32000
      },
      {
        "product_id": 18,
        "fixed_price": 28500
      }
    ]
  }'

Assign Customers to Price List

Assigns customers to a price list. Customers previously on other lists will be moved to this list. Customers not in the provided list will be unassigned.

Path Parameters

price_list_id

integer

required

The price list ID

Request Body

customer_ids

array

required

Array of customer IDs to assign to this price list

Response

detail

string

Success message with count of customers assigned

Example

curl -X PUT "https://api.example.com/price-lists/1/customers" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_ids": [10, 15, 22, 33]
  }'

Response Example

{
  "detail": "4 cliente(s) asignados a la lista 1."
}

Resolve Price for POS

Calculates the final price to apply for a product, considering the customer’s assigned price list. This is the core pricing logic used by the POS system.

Path Parameters

product_id

integer

required

The product ID to price

Query Parameters

customer_id

integer

Optional customer ID. If provided, checks for custom pricing

Response

product_id

integer

The product ID

customer_id

integer

The customer ID (if provided)

price_list_id

integer

The price list ID used (if applicable)

resolved_price

decimal

The final price to charge

source

string

Price source: "price_list" or "base_price"

Pricing Logic

The system resolves prices in the following priority order:

If the customer has a price list assigned AND the product has a fixed price in that list → use the fixed price
Otherwise → use the product’s base precio_neto

Example

# Get price for product 5 when selling to customer 10
curl -X GET "https://api.example.com/price-lists/resolve-price/5?customer_id=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Examples

With Price List:

{
  "product_id": 5,
  "customer_id": 10,
  "price_list_id": 1,
  "resolved_price": 45000,
  "source": "price_list"
}

Without Price List (Base Price):

{
  "product_id": 5,
  "customer_id": 10,
  "price_list_id": 1,
  "resolved_price": 52990,
  "source": "base_price"
}

No Customer (Anonymous Sale):

{
  "product_id": 5,
  "resolved_price": 52990,
  "source": "base_price"
}

Error Handling

404 Not Found

Returned when price list or referenced products/customers don’t exist:

{
  "detail": "Lista de precios 99 no encontrada."
}

{
  "detail": "Productos no encontrados: [15, 23]"
}

{
  "detail": "Clientes no encontrados: [101, 105]"
}

{
  "detail": "Producto 999 no encontrado o inactivo."
}

Getting Started

SaaS Management

Sales

Products & Inventory

Customers & Suppliers

Cash & Reports

Administration

​Overview

​How Price Lists Work

​Create Price List

​Request Body

​Response

​Example

​List Price Lists

​Response

​Example

​Get Price List Detail

​Path Parameters

​Response

​Example

​Response Example

​Update Price List

​Path Parameters

​Request Body

​Example

​Delete Price List

​Path Parameters

​Response

​Example

​Assign Products to Price List

​Path Parameters

​Request Body

​Response

​Example

​Assign Customers to Price List

​Path Parameters

​Request Body

​Response

​Example

​Response Example

​Resolve Price for POS

​Path Parameters

​Query Parameters

​Response

​Pricing Logic

​Example

​Response Examples

​Error Handling

​404 Not Found

Build docs developers (and LLMs) love

Overview

How Price Lists Work

Create Price List

Request Body

Response

Example

List Price Lists

Response

Example

Get Price List Detail

Path Parameters

Response

Example

Response Example

Update Price List

Path Parameters

Request Body

Example

Delete Price List

Path Parameters

Response

Example

Assign Products to Price List

Path Parameters

Request Body

Response

Example

Assign Customers to Price List

Path Parameters

Request Body

Response

Example

Response Example

Resolve Price for POS

Path Parameters

Query Parameters

Response

Pricing Logic

Example

Response Examples

Error Handling

404 Not Found