Cart Validation Service

Cart Validation Service Documentation

Use Case Description

The Cart Validation Service allows a third-party system to validate a customer's cart, determining if promotions can be applied to the selected products. The input is a JSON structure representing the cart, and the output is the updated cart with any discounts or promotions applied.

Actors

External System: The external system (ERP,WMS ecc...) initiating the order processing and stock transfer.

Cart Validation: The service that processes the cart and applies the relevant promotions.

Promotion Engine: The system that evaluates and applies promotions to the cart items.

Preconditions

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

APIs Used

The cart validation process involves the following APIs:

Cart Validation: Receives the cart in JSON format, validates the items, retrieves updated prices, applies promotions, and returns the updated cart.

Main Success Scenario

The e-commerce site prepares a shopping cart in JSON format containing the product information the customer intends to purchase.

The e-commerce site invokes the Cart Validation API, passing the cart in JSON format.

The Cart Validation API returns an updated cart with any applied discounts.

Alternate Flows

Product Not Available: If a product in the cart is unavailable, the Cart Validation Service returns an error indicating the item's unavailability.

Promotion Not Applicable: If there are no applicable promotions, the Cart Validation Service returns the cart without any discounts applied.

Service Not Available: If the Product Catalog Service or the Promotion Engine is unavailable, the system must retry the operation or notify the operator to handle the situation manually.

JSON Structure for Sale Document

Input JSON Example

Callback Response Example

transactionId & rowId

Please note that the service returns a cart with a specific transactionId, and each line item in the cart has a unique rowId. These pieces of information must be used without fail if the Save sale service is to be invoked.

Explanation of the `appliedPromotions` Parameter

The appliedPromotions parameter in the response contains detailed information about the promotions that have been successfully applied to the items in the cart. This parameter is crucial for understanding which discounts or special offers have been utilized and how they affect the overall pricing of the cart.

Any others discounts (like sale or manual) are listed for each item in the cart:

discount: percentage value of the discount

discountType: type of discount, "P" for percentage, "V" for value

discountReasonDescription: description of the discount reason

discountReason: code for the discount reason

autoDiscountType: type of automatic discount applied, "SALE" for sale

discountAmount: value of the applied discount, either automatic or percentage-based

discountTotalAmount: total amount of discounts applied

Structure of `appliedPromotions`

The appliedPromotions parameter is essential for ensuring transparency in how discounts and promotions are applied, helping both customers and operators understand the savings and benefits realized during the transaction.

The appliedPromotions parameter is an array of objects, where each object represents a single promotion that has been applied to the cart. The key attributes of each promotion object include:

entityCode: (string) The code identifying the business entity (e.g., store, franchise) to which the promotion is linked.

advantage: (number) The monetary value of the benefit provided by the promotion, typically representing the discount amount applied to the item or the total cart.

percSconto: (number) The percentage of the discount applied by the promotion. For example, if the promotion provides a 20% discount, this field would show 20.

applicationMethod: (string) Describes how the promotion is applied, such as whether it is cumulative with other promotions or exclusive. For example, it could be "CUMULATIVE" if the promotion can be combined with others.

rowId: (string) The unique identifier for the specific row in the cart to which this promotion has been applied. This allows for tracking which items in the cart have been discounted.

idPromozione: (string) The unique identifier of the promotion itself. This ID can be used for reference or reporting purposes.

promotionType: (string) Describes the type of promotion applied, such as "3X2" for a buy-three-get-two-free offer.

advantageDescription: (string) A brief description of the benefit provided by the promotion. This might be something like "Apply 3x2" or "20% off."

branchCode: (string) The code of the store or branch where the promotion is being applied.

promotionDescription: (string) A more detailed description of the promotion, potentially providing context or details about the offer (e.g., "Special 3x2 summer").

channelType: (string) The channel through which the promotion is available, such as "IN_STORE" or "ONLINE."

This section provides a clear explanation of the appliedPromotions parameter, detailing its structure, usage, and impact on the cart's final pricing.

Example of `appliedPromotions` in the Response

Here is an example of how the appliedPromotions parameter might look in a response:

"appliedPromotions": [
    {
        "entityCode": "501",
        "advantage": 155,
        "percSconto": 100,
        "applicationMethod": "CUMULATIVE",
        "rowId": "8813b347-948c-4911-bf1a-bfd050ee4280",
        "idPromozione": "4c7ab244-99fb-4d59-bc7d-1e89308e8ca7",
        "promotionType": "3X2",
        "advantageDescription": "Apply 3x2",
        "branchCode": "9999",
        "promotionDescription": "Special 3x2 summer"
    }
]

How `appliedPromotions` Affects the Cart

Total Discount Calculation: The total value of all applied promotions is calculated and reflected in the totalDiscountAmount field under the totals section of the response.

Item-Level Discount: Each item in the cart can have its price reduced based on the applicable promotions. The discounted amount is included in the discountAmount field of the corresponding item.

Final Price Adjustment: The final price of the cart, after applying all relevant promotions, is reflected in the grandTotal field under the totals section.

Sequence Diagram

INFO

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

Code Examples in Node.js

This documentation provides a detailed description of the Cart Validation Service, with alternate flows, JSON structure examples, sequence diagrams, and code examples in Node.js.

Cart Validation Service