Price List Variant Prices API
This release expands the Price Lists API with support for variant-level fixed prices, making it possible to inspect and clear the fixed prices configured in a custom price list.
Variant prices as a price list sub-resource
OpenTiendas now exposes variant prices as a sub-resource of price lists.
A price list variant price represents a fixed price configured for a specific product variant within a custom price list. This allows a price list to define exact prices for selected variants, instead of relying only on global, brand or category discounts.
The new sub-resource is available under the price list resource:
/api/v1/price-lists/{id}/prices/
This design keeps fixed prices conceptually owned by the price list. Even when external systems such as ERPs, CRMs or PIMs display pricing conditions from the product or variant view, the price itself belongs to the commercial price list.
Managing these prices through the price list resource provides a single and predictable API path for the same data, avoids inconsistencies between endpoints, and makes full price list synchronization easier to model.
Available endpoints
The following endpoints are now available:
GET /api/v1/price-lists/{id}/prices/
DELETE /api/v1/price-lists/{id}/prices/
The GET endpoint returns a paginated list of variant prices configured in the selected price list.
The DELETE endpoint removes all variant prices configured in the selected price list.
This first iteration does not create, update or bulk synchronize variant prices. Those operations will be handled separately through a future bulk update endpoint.
Listing variant prices
A new endpoint is available to retrieve the fixed prices configured for a specific price list:
GET /api/v1/price-lists/{id}/prices/
The endpoint returns customer-specific variant prices configured in the selected price list. It does not return the standard catalog prices configured for variants.
Each item represents a variant-level fixed price and includes product, variant and supplier identifiers when available, together with the configured price and purchase quantity conditions.
Example response item:
{
"variant_id": 45892,
"variant_internal_id": "VAR-B2B-RED-M",
"product_id": 7310,
"product_internal_id": "PROD-BASIC-TEE",
"ean": "8430000001234",
"sku": "BASIC-TEE-RED-M",
"supplier_id": 22,
"supplier_internal_id": "SUP-TEXTILE",
"display_name": "Basic T-shirt Red - Size M",
"price": {
"amount": "12.90",
"currency": "EUR"
},
"min_quantity": 10,
"quantity_factor": 5
}
The display_name field is informational and is returned in the store’s primary locale, for example es-ES.
All fields are returned by this endpoint. When a value is not defined, it is returned as null.
Filtering, ordering and pagination
The list endpoint follows the standard paginated response format used by the OpenTiendas API.
It supports standard pagination parameters:
page,per_page.
The default per_page value is 100, and the maximum value is 500.
Variant prices can be filtered by several identifiers, including:
variant_id,variant_internal_id,product_id,product_internal_id,ean,sku,supplier_id,supplier_internal_id.
Multiple filters can be combined in the same request, making it possible to locate a specific variant price using the identifiers available in the external system.
Results can also be ordered by the same identifier fields, using ascending or descending order.
Example requests:
GET /api/v1/price-lists/3/prices/?variant_internal_id=VAR-B2B-RED-M
GET /api/v1/price-lists/3/prices/?ean=8430000001234
GET /api/v1/price-lists/3/prices/?sku=BASIC-TEE-RED-M&supplier_internal_id=SUP-TEXTILE
This makes the endpoint useful for ERPs and other integrations that need to inspect whether a specific reference already has a fixed price in a custom price list.
Minimum quantities and quantity multiples
Variant prices can also include purchase quantity conditions.
The min_quantity field represents the minimum quantity that must be purchased for that variant when the price list applies.
The quantity_factor field represents the quantity multiple that must be respected when purchasing the variant.
For example, a variant can be configured so that customers using the price list must buy at least 5 units and then increase the quantity in multiples of 5.
Quantity discounts are not included in this endpoint. They remain outside the scope of this iteration and will be handled separately in a future improvement.
Deleting all variant prices from a price list
A new endpoint is also available to remove all fixed prices by variant from a price list:
DELETE /api/v1/price-lists/{id}/prices/
This operation deletes every variant price configured in the selected price list, including any variant-level minimum quantity and quantity multiple values.
It does not delete the price list itself, and it does not modify the price list configuration. Fields such as active state, minimum order amount, global discount, category discounts and brand discounts remain unchanged.
After deletion, variants affected by the price list no longer have fixed prices from that price list. They may still be affected by other price list rules, such as brand, category or global discounts.
The endpoint returns 204 No Content when all variant prices have been successfully removed.
This can be useful when an integration needs to rebuild the fixed prices of a price list from an external system and wants to clear the previous variant-level pricing data first.
Summary
This release expands price list API coverage by:
- defining variant prices as a price list sub-resource,
- adding an endpoint to list variant-level fixed prices,
- exposing product, variant and supplier identifiers for each configured price,
- including price, minimum quantity and quantity multiple information,
- supporting filtering, ordering and pagination,
- and adding an endpoint to delete all variant prices from a price list.
These changes provide the first API layer for working with fixed prices by reference in custom price lists, while keeping the price list as the owner of the data.
What's next
Upcoming improvements will focus on:
- adding bulk update support for fixed prices by reference in custom price lists,
- enabling external systems to create and synchronize variant prices at scale,
- expanding price list coverage for more advanced custom pricing use cases,
- and continuing to evolve the API as a robust integration layer for ERPs, PIMs, CRMs and custom synchronization services.