Insert Product Price

Insert Product Prices

This API allows adding a product and its price to a specific price list by specifying the PRICE_LIST_TYPE (type of price list), PRICE_LIST_CODE (price list code), and item_code (product code). The client can also provide a start_date and price for the product.

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.

History of product prices

The suite allows you to manage the history of price changes for a product, each price has a start of validity and end of validity date.
A product considered a given document will have only one price per type (sale, purchase, invoice, etc...).

Valid start date passed

If you want to add a price to the product, but with a validity start date in the past (compared to the date of invocation of the service), the date of validity ceased to be the day before the validity start date of the next price will also be valorised.

Starting

The product MAGLIA1234 has a sales price of €19.99 valid starting from 20/05/2024 and there is no price with a subsequent date.

new price with validity date before 05/20/2024

The insertion of a price for the product MAGLIA1234 with price 20.99€ valid starting from 15/05/2024 also causes its ceased validity date to be updated to ** 19/05/2024**.

Document with movement date 05/15/2024

If a document with movement date 15/05/2024 is registered, the price of the product will be €20.99.

The historical price progression of the product MAGLIA1234 will be:

from the date 15/05/2024 to 19/05/2024 the price is €20.99.

from the date 20/05/2024 onwards the price is €19.99.

Future validity start date

If you want to add a price to the product, but with a future validity start date (with respect to the date of invocation of the service), two cases can occur.

First price

In this case the price will be entered with the desired validity start date and termination date of 2999-12-31.

Not first price

Prices by size range

It is possible to add prices to products managed with price range per size by valuing dimensiong_grupping with the range.

Specify the value BABY in the dimensiong_grupping field and the price in price.

{
    "item_code": "MB1234564",
    "start_date": "2024-05-06",
    "price": "150",
    "dimension_grouping": "BABY"
}

In this way all sizes in the range will assume that price starting from the start_date.

Preconditions

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

The PRICE_LIST_TYPE and PRICE_LIST_CODE must correspond to an existing price list in the system.

The item_code provided must correspond to an existing product in the system.

Main Success Scenario

The API client sends a POST request with the PRICE_LIST_TYPE, PRICE_LIST_CODE, item_code, start_date, and price.

If successful, the API returns a response with a success message, the prog_id of the inserted price, the effective price, and the start_date.

Alternate Flows

Price List Not Found: If the specified PRICE_LIST_CODE does not exist, the API returns an error message:

{
  "message": "Price list not found"
}

Product Not Found: If the specified item_code does not exist, the API returns an error message:

{
  "message": "Product not found with item_code: {{item_code}}"
}

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

Example Node.js code for adding a product to a price list:

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Examples

Product priceProduct prices by groupping size

{
    "success": true,
    "pricesInserted": [
        {
            "prog_id": 192658,
            "price": 150.24,
            "start_date": "2024-05-09"
        }
    ]
}

🟠401Authentication failed

🟠403Operation not allowed

🟠404This dimension grouping doesn't exits

🟠422Esiste già un prezzo per il prodotto in quella data

🟠404Product not found with item_code

🟠422Validità prezzo non corretta

Insert Product Price