¶ Overview
The Cart and Order models manage different types of totals at different levels.
¶ The TotalMap Model
The Cart model and its total-container sub-models has the same structure to hold totals called TotalModel.
That is a special field called totals with a map of totals as value.
This maps of totals has the form:
{
"totalCode1": <value for total 'tocalCode1'>,
"totalCode2": <value for total 'tocalCode2'>,
"totalCode3": <value for total 'tocalCode3'>,
...
}
Where there could be any number of fields totalCodeN that act as identification codes for the each total, and the values on the right side are valid JavaScript numbers (decimal or integer, possitive, zero or even negative, depending on the case).
The possible total codes and its interpretation depends on which model the totals belong to.
For example, a cart item could have something like this:
{
"unit": 120.5,
"subtotal": 241,
"unitDiscount": -5,
"discount": -10,
"tax": 2.5,
"grandTotal": 233.5
}
¶ Totals in the Cart
The Cart models that are total containers are:
- Cart: The
cartitself. - Cart Item: Each of the cart items held in the array
cart.items. - Cart Shipping Address: Each of the shipping addresses in the array
cart.shippingAddresses. - Cart Shipping Method: Each of the shipping methods on all cart shipping address. That would be all the items in the arrays
cart.shippingAddresses[*].shippingMethods.
That means that all those models have a field totals with a TotalMap as value.
For each of those models, there is a set of possible totals, each of them having its own strategy for obtention or calculation. Even having dependencies between them of with totals in other model inside the same cart.
Here is a pruned version of the cart model with all the totals at different levels. Take into account that for simplicity this shows only the totals and related enclosing fields, but not all actual fields in a valid cart.
{
// (other cart fields...)
"items": [
{
// (other cart item fields...)
"totals": { // Item totals
"unit": 0, // Unit price
"subtotal": 0, // Item price taking into account the qty
"unitDiscount": 0, // Discount per unit
"discount": 0, // Discount on the item
"tax": 0, // Taxes on the item
"grandTotal": 0 // Total item price
}
}
],
"shippingAddresses": [
{
// (other shipping address fields...)
"shippingMethods": [
{
// (other shipping method fields...)
"totals": { // Shipping method totals
"shipping": 0 // Shipping cost for the method
}
}
],
"totals": { // Shipping address totals
"shipping": 0 // Shipping code for the address
}
}
],
"totals": { // Cart totals
"subtotal": 0, // Sum of items subtotals
"shipping": 0, // Sum of addresses shiping totals
"discount": 0, // Total cart discount
"globalDiscount": 0, // Overall cart discount
"tax": 0, // Total cart taxes
"globalTax": 0, // Overall cart taxes
"grandTotal": 0 // Total to pay
},
}
¶ Cart Totals
The main totals in the cart.
{
"subtotal": 0, // 1. Subtotal: Sum of items subtotals
"shipping": 0, // 2. Shipping: Sum of addresses shiping totals
"discount": 0, // 3. Discount: Total cart discount
"globalDiscount": 0, // 4. Global Discount: Overall cart discount
"tax": 0, // 5. Tax: Total cart taxes
"globalTax": 0, // 6. Global Tax: Overall cart taxes
"grandTotal": 0 // 7. Grand Total: Total to pay
},
-
Subtotal (
subtotal): Plane price to pay for all items in the cart without discounts, taxes or management fees. It is calculated as the sum of all itemsshipingtotals. -
Shipping Total (
shipping): Shipping price including the management of all shipping addresses in the cart. It is calculated as the sum of all shipping addressesshipingtotals. -
Discount Total (
discount): The total discount of the cart, including any possible global discount, plus the individual applied item discounts. It is calculated as the sum of itemsdiscounttotals plus the cartglobalDiscount. -
Global Discount (
globalDiscount): In this API version it is always0. In future versions global discount rules could be supported. -
Tax Total (
tax): The total taxes applied to the cart, including any possible global discount tax, plus the individual applied item taxes. It is calculated as the sum of itemstaxtotals plus the cartglobalTax. -
Global Tax (
globalTax): In this API version it is always0. In future versions global tax rules could be supported. -
Grand Total (
grandTotal): Final value to pay, calculated based on other cart totals assubtotal + shipping + tax + discount.
¶ Item Totals
Totals applied to each individual item.
{
"unit": 0, // 1. Unit Price: Price of one unit of the product item
"subtotal": 0, // 2. Subtotal: Item price taking into account the qty
"unitDiscount": 0, // 3. Unit Discount: Discount applied on each unit of the product item
"discount": 0, // 4. Discount: Discount on the item
"tax": 0, // 5. Tax: Taxes on the item
"grandTotal": 0 // 6. Grand Total: Total item price
},
-
Unit Price (
unit): Unit price of the product item. It is set based on the cart owner calculated price list and the cart currency, using theregularprice type. -
Subtotal (
subtotal): Plane price to pay for all the item taking into account the quantity in the cart without discounts, taxes or management fees. It is calculated asunit * qty. -
Unit Discount (
unitDiscount): Discount per unit of the product item. It is set based on the cart owner calculated price list, the cart currency and the item qty (tier pricing), using theregularprice type. Its value is always<= 0 -
Discount Total (
discount): Total discount of the item taking into account the quantity in the cart. It is calculated asunitDiscount * qty. -
Tax Total (
tax): The total taxes applied to the cart item. It is calculated based on the applicable tax rules. Having the applied taxes (available in the arrayitem.additionalInformation.taxes), the percentage tax rate is summed up and divided by100. That total rate is multiplied by the partial item valuesubtotal + discount, resulting in the item total tax. -
Grand Total (
grandTotal): Total of the item including discounts and fees. It is calculated as itemsubtotal + tax + discount.
¶ Shipping Address Totals
Totals of shipping management for each individual shipping address.
{
"shipping": 0 // 1. Shipping Total: Shipping code for the address
},
- Shipping Total (
shipping): Shipping price including the management of the shipping address with all its shipping methods. It is calculated as the sum of all its shipping methodsshipingtotals.
¶ Shipping Method Totals
Totals of shipping management for each individual shipping method used on each of the shipping addresses.
{
"shipping": 0 // 1. Shipping Total: Shipping cost for the method
},
- Shipping Total (
shipping): Shipping price including the management of all items in the method'sitemsarray (which is not the same as the cart'sitemsarray). It is set based on the items to be shipped (shipping methoditemsarray), thecarrierCodeand themethodCode.
¶ Totals in the Order
The order totals are exactly the same as the cart totals.
¶ Totals Dependencies
Based on the calculations of the different totals in the Cart and Order models, there are dependencies between them.
In this figure, the arrows show the dependencies from each dependent total to its dependencies.
The totals rounded with a square are independent in terms of the cart itself. Their values are obtained from other services, as explained in Totals in the Cart section.
