Get product prices

Retrieve Product Prices

This API allows the retrieval of product prices for a specific product {ITEM_CODE}, with options to filter by entity reference (entity_code), price list (price_list), price list type (price_list_type), and validity start date (start_date). If no start_date is provided, the API returns the prices valid on the day of the API call.

To retrieve all the prices of a price list in a single paginated flow, instead of one call per product, use Get prices from price list.

Product pricing

For more detail about product pricing features please refer to Product pricing and Defining Product Pricing.

Actors

API Client: The system or user initiating the request.

4ws.trade: The backend system that processes the request.

Preconditions

The external system must have the necessary permissions and access to the service, please refer to Authentication.

The {ITEM_CODE} must be valid within the system.

If specified, entity_code, price_list and price_list_type (A, V, F or R) must be recognized by the system.

Main Success Scenario

The API retrieves the list of prices associated with {ITEM_CODE}, optionally filtered by entity_code, price_list, price_list_type and start_date. If the product has variant-based pricing, each variant's price is included in the results.

{
  "item_code": "example_item",
  "price_management_type": "ITEM",
  "item_prices": [
    {
      "start_date": "2024-05-01",
      "end_date": "2024-12-31",
      "price": 33,
      "price_list_type": "R",
      "currency": "EUR",
      "dimension_level1": "size_L",
      "dimension_level2": "color_Red",
      "dimension_level3": "material_Wool",
      "dimension_level4": "style_Casual",
      "dimension_level5": "fit_Regular",
      "price_list": "seasonal_discount",
      "price_list_entities": [
        "store_1"
      ]
    }
  ]
}

INFO

For sale (discount) price lists:

The price field indicates the discounted price of the product.

The discount_perc field represents the percentage discount applied to the selling price.

🔹 Rule for Interpreting price and discount_perc

The API exposes two alternative fields to represent a product discount:

price → the final discounted price

discount_perc → the discount percentage applied to the base selling price (selling_price)

Only one of the two fields is provided at a time: when price is provided, discount_perc is null, and vice versa.

The external system must compute the missing value based on the one that is present.

🔸 Case 1 — price provided

If the final price (price) is provided, the external system must calculate the discount percentage as follows:

Example:

selling_price = 100

price = 80
→ discount_perc = 20%

🔸 Case 2 — discount_perc provided

If the discount percentage (discount_perc) is provided, the external system must calculate the final price (price) as follows:

Example:

selling_price = 100

discount_perc = 15
→ price = 85

Alternate Flows

Missing or Invalid {ITEM_CODE}:
If {ITEM_CODE} is not recognized, the API returns an error indicating "item_code not found".

{
  "message": "Invalid input",
  "errors": {
    "msg": "item_code not found",
    "param": "item_code",
    "location": "body"
  }
}

No Active Prices Available:
If there are no active prices for the specified filters, an empty item_prices list is returned.

Errors for Other Parameters:
If parameters such as price_list or price_list_type are invalid, the API returns an error message with the specific parameter issue.

Sequence Diagram

Best Practices

Please refer to Best Practices for Error Handling in External System for best practices on implementation.

Code Examples in Node.js

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200OK

application/json

Bodyapplication/json

Example

{
    "item_code": "quis",
    "price_management_type": "ITEM",
    "item_prices": [
        {
            "start_date": "2024-05-02",
            "end_date": "2024-05-01",
            "price": 33,
            "price_list_type": "R",
            "currency": "EUR",
            "dimension_level1": "in aute fugiat",
            "dimension_level2": "minim deserunt",
            "dimension_level3": "esse sunt eiusmod veniam Lorem",
            "dimension_level4": "Ut mollit",
            "dimension_level5": "Ut cillum",
            "price_list": "sed elit eiusmod labore",
            "price_list_entities": [
                "1"
            ]
        }
    ]
}

🟠422Prodotto non trovato

🟠401Authentication failed

🟠403Operation not allowed

🟠422Unique constraint error

Get product prices

Retrieve Product Prices#

Actors#

Preconditions#

Main Success Scenario#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrieve Product Prices

Actors

Preconditions

Main Success Scenario

Alternate Flows

Sequence Diagram

Code Examples in Node.js