Get product prices

Retrive Product Prices

This API allows the retrieval of product prices for a specific product {ITEM_CODE}, with options to filter by specific parameters such as 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 will return prices valid on the day of the API call by default.

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 document creation service, please refer to Authentication.

The {ITEM_CODE} must be valid within the system.

If specified, the entity_code, price_list, and price_list_type 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, and price_list_type. 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-02",
      "end_date": "2024-05-01",
      "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

If the price_list_type is SALE:

The price field indicates the discounted price of the product.

The discount_perc field represents the percentage discount applied to the sale 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 or selling price (selling_price)

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

The 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 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 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 list is returned.

Errors for Other Parameters:

If parameters such as price_list or price_list_type are invalid, the API will return 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

Body

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

Retrive Product Prices#

Actors#

Preconditions#

Main Success Scenario#

Alternate Flows#

Sequence Diagram#

Code Examples in Node.js#

Request

Request Code Samples

Responses

Retrive Product Prices

Actors

Preconditions

Main Success Scenario

Alternate Flows

Sequence Diagram

Code Examples in Node.js