CartItem

The CartItem object represents a single entry within the shopping cart. Unlike a simple SKU, it is an "enriched" entity that aggregates logistical, fiscal, and shipping data calculated in real-time to allow for precise checkout management.

CartItem Definition

Property	Type	Description
id	string (UUID)	Unique identifier for the entry in the cart.
skuId	string (UUID)	Unique identifier of the specific SKU added.
variantId	string (UUID)	Identifier of the parent variant.
productId	string (UUID)	Identifier of the root product.
variantName	string	Variant name displayed in the cart.
variantSlug	string	Slug for the product page link.
coverUrl	string	URL of the item's cover image.
quantity	number	Quantity selected by the user.
available	number	Quantity actually available in stock.
isAvailable	boolean	Indicates if the item is currently purchasable.

---

Pricing and Currency

Price values reflect the state at the time of adding to the cart, including any already calculated quantity discounts (tier pricing).

Property	Type	Description
priceId	string (UUID)	ID of the applied price list.
originalPrice	number	Base unit price (gross).
netAmount	number	Net unit price.
totalAmount	number	Total gross for the line item (unit price * quantity).
currencyCode	string	Currency code (e.g., EUR).
cadence	string	Payment frequency (e.g., once).

---

Logistics and Shipping

This data allows the webround.com engine to automatically calculate shipping costs and manage the physical constraints of the package.

Property	Type	Description
packageWeight	number	Package weight expressed in grams (e.g., 18500 = 18.5kg).
packageVolume	number	Package volume (cm³).
deliveryMethods	string[]	Supported delivery methods (e.g., shipping, pickup).
shippingZones	ShippingZone[]	Geographical zones and specific surcharges/taxes.
shippingMethods	ShippingMethod[]	List of available carriers with relative costs and delivery times (ETA).
taxZones	TaxZone[]	List of applicable VAT rates based on the destination country.

Object Example

{
    "skuId": "43add257-6334-4f25-b0bd-4db878dd9308",
    "priceId": "a4884383-52cc-419a-a605-69fe067f555f",
    "quantity": 1,
    "originalPrice": 100,
    "comparePrice": 0,
    "netAmount": 100,
    "totalAmount": 100,
    "currencyCode": "EUR",
    "defaultTaxRate": 0,
    "cadence": "once",
    "shippingZones": [
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "zoneId": "0f27b303-4fa6-4469-948d-61a4f7103a66",
            "label": "Zona Italia",
            "countryCode": "IT",
            "surchargePricing": {},
            "taxRate": 22
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "zoneId": "c19ccb31-5556-4e4f-bc9a-51ff293bc262",
            "label": "Zona Francia",
            "countryCode": "FR",
            "surchargePricing": {
                "eur": {
                    "base": 0,
                    "percentage": 0
                }
            },
            "taxRate": 20
        }
    ],
    "shippingMethods": [
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "30ba1461-8f03-4586-a850-d69416aeef38",
            "label": "Spedizione Standard Italia",
            "provider": "Poste Italiane",
            "pricing": {
                "eur": {
                    "base": 8,
                    "perKg": 0.5,
                    "toWeight": 100000,
                    "perVolume": 0,
                    "fromWeight": 10000,
                    "enableFreeShipping": true,
                    "freeShippingThreshold": 250
                }
            },
            "availableCountries": [
                "IT",
                "SM",
                "CH"
            ],
            "etaMin": 3,
            "etaMax": 7,
            "enabled": true,
            "maxWeight": 100000,
            "maxVolume": 5000000
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "e16fe755-8fce-4c9d-a157-f7e67a6dae9b",
            "label": "Spedizione Italiana economica",
            "provider": "Provider",
            "pricing": {
                "eur": {
                    "base": 10,
                    "perKg": 0,
                    "perVolume": 0
                }
            },
            "availableCountries": [
                "IT"
            ],
            "etaMin": 1,
            "etaMax": 3,
            "enabled": true,
            "maxWeight": 0,
            "maxVolume": 0
        },
        {
            "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
            "methodId": "1758fedd-111f-4b02-973c-5563a5e6a9f1",
            "label": "Spedizione Standard Francia",
            "provider": "France post",
            "pricing": {
                "eur": {
                    "base": 14,
                    "perKg": 0.85,
                    "toVolume": 0,
                    "toWeight": 100000,
                    "perVolume": 0,
                    "fromVolume": 0,
                    "fromWeight": 4000
                }
            },
            "availableCountries": [
                "FR"
            ],
            "etaMin": 3,
            "etaMax": 14,
            "enabled": true,
            "maxWeight": 0,
            "maxVolume": 0
        }
    ],
    "taxZones": [
        {
            "id": "84f26098-4823-4f3c-82d0-44733e4d9d5d",
            "countryCode": "IT",
            "rate": 22,
            "isDefault": true
        },
        {
            "id": "ebdbe0cb-93c7-4f47-8a51-513828f92b88",
            "countryCode": "FR",
            "rate": 20,
            "isDefault": false
        }
    ],
    "available": 9,
    "isAvailable": true,
    "variantId": "0f669b79-af65-4433-96e3-5eca8e1b8852",
    "productId": "d6128604-7b88-4079-9b91-a3a21584376c",
    "variantSlug": "sbarra-multigrip-a-muro",
    "deliveryMethods": [
        "shipping",
        "pickup"
    ],
    "packageWeight": 18500,
    "packageLength": 100,
    "packageWidth": 30,
    "packageHeight": 30,
    "packageVolume": 90000,
    "allowBackorder": false,
    "purchaseRestock": true,
    "allowFreeShipping": true,
    "forceFreeShipping": false,
    "options": [],
    "variantName": "Sbarra multigrip a muro",
    "coverUrl": "https://webrounddev.b-cdn.net/rMa8bmEA2Yg9aYk5PgZPejecmIB2/a7734977-c5b1-49a4-911c-0b0bf745bd4f/commerce/images/1755068526900-9048_2-multigrip-bar-indoor-micacea-1536x1536.jpg",
    "id": "3afdc08d-e1e4-4a6d-b683-0c506d984deb"
}

Dynamic Calculation

Thanks to the presence of shippingMethods and taxZones within each CartItem, the SDK calculates the cart total and shipping costs in real-time as soon as the user changes the destination address, without the need to reload the entire page.