Shipping Zone

The ShippingZone object defines the geographical, fiscal, and logistical rules applied to a specific product based on the customer's location. Each item in the cart (CartItem) contains its own array of zones to allow the webround.com engine to calculate shippability, taxes, and surcharges in real-time.

ShippingZone Definition

Property	Type	Description
productId	string (UUID)	ID of the product associated with this zone rule.
zoneId	string (UUID)	Unique identifier for the logistical/geographical zone.
label	string	Descriptive name of the zone (e.g., "Italy Zone", "France").
countryCode	string	ISO country code (e.g., IT, FR).
taxRate	number	The VAT rate applied to the product when shipped to this country.
surchargePricing	Object	Currency map containing extra costs (base and percentage) for the zone.

Object Example

{
    "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
    "zoneId": "0f27b303-4fa6-4469-948d-61a4f7103a66",
    "label": "Italy Zone",
    "countryCode": "IT",
    "surchargePricing": {},
    "taxRate": 22
}

Surcharge Pricing Detail

The surchargePricing object is designed for zones that involve customs fees or duties. It does not represent a shipping cost, but rather a price surcharge determined by any additional expenses beyond those of the shipping method.

"surchargePricing": {
    "eur": {
        "base": 5.00,
        "percentage": 0
    }
}

Automatic Matching

When a user sets a shipping address, the system scans the shippingZones array of each item in the cart. It looks for the countryCode matching the address to instantly update totals and verify shipping availability to that country.