Shipping Data

This page describes the objects used to manage logistics and customer localization. The primary Shipping object is located within wr.cart.state.shipping: it is used to track compatible shipping methods, calculated costs, and the currently selected method in real-time.

Shipping (State Object)

Represents the current shipping status for the active cart. The webround.com engine updates this object whenever the address or cart content changes.

Property	Type	Description
compatible	boolean	Indicates if all items in the cart can be shipped to the chosen destination.
methods	EnrichedMethod[]	Array of valid shipping methods, including net costs, taxes, and gross totals.
selected	EnrichedMethod	null
reason	string	null

---

ShippingAddress

Represents the physical address saved in the customer's profile or entered during checkout for zone and tax calculations.

Property	Type	Description
id	string (UUID)	Unique identifier for the address.
fullName	string	Recipient's full name.
company	string	Company name (optional).
addressLine1	string	Primary address (Street, Square, etc.).
addressLine2	string	Apartment, suite, or additional unit information.
city	string	Destination city.
postalCode	string	ZIP or postal code.
countryCode	string	ISO country code (e.g., IT). Essential for zone calculation.
isDefaultShipping	boolean	Indicates if this is the default shipping address.

---

EnrichedMethod (Method Details)

This is the object contained within the methods array. It extends Shipping Method with real-time economic calculations.

Property	Type	Description
methodId	string	Shipping method ID.
label	string	Service name (e.g., "Standard Italian Shipping").
costNet	number	Net shipping cost calculated based on total weight/volume.
surchargeNet	number	Surcharge applied by the Shipping Zone (e.g., duties or remote areas).
vatRate	number	VAT rate applied to the shipping.
vatAmount	number	Tax amount calculated on the total shipping cost.
totalGross	number	Final total cost (Net + Surcharge + VAT).

---

DeliveryMethod

Defines the supported delivery modes for a specific item. This is an Enum type:

• 'pickup': In-store pickup.
• 'shipping': Shipping via courier.
• 'digital': Digital product without physical shipping (Requires Stripe Tax and correct configuration on each product).
• 'none': No delivery method required.

---

CartItemWithDelivery

Represents a cart item enriched with logistics management information.

Property	Type	Description
id	string	Unique ID of the instance in the cart.
skuId	string	ID of the associated product SKU.
deliveryMethods	DeliveryMethod[]	List of delivery methods available for this specific item.

---

JSON Example: wr.cart.state.shipping

{
    "compatible": true,
    "methods": [
        {
            "methodId": "30ba1461-8f03-4586-a850-d69416aeef38",
            "label": "Standard Italian Shipping",
            "provider": "Poste Italiane",
            "costNet": 12.35,
            "surchargeNet": 0,
            "vatRate": 22,
            "vatAmount": 2.717,
            "totalGross": 15.067
        }
    ],
    "selected": {
        "methodId": "30ba1461-8f03-4586-a850-d69416aeef38",
        "totalGross": 15.067
    },
    "reason": null
}

Calculation Workflow

1. The user enters a ShippingAddress.
2. The system reads the countryCode.
3. Compatible Shipping Methods for that country are filtered.
4. For each method, the totalGross is calculated by adding the base cost (pricing), item weight, and any zone surcharge.

warning

Any calculation occurring with these elements is purely visual. During the checkout phase, the system re-executes all calculations on the server to ensure reliability and precision.