This tutorial covers how to provide multiple shipping addresses for one cart. It furthermore explains how multiple shipping addresses relate to the cart’s shipping rate and tax rates as well as the deliveries of the order.
Line Item Shipping Address
When multiple shipping addresses are needed for a cart, you do so by associating a line item with one or more addresses.
All addresses are to be captured in the cart property called itemShippingAddresses.
When creating an address, you have to provide a key which is unique in this cart.
The key will become the reference when you associate a line item with a shipping address.
The association is achieved with the line item action called setLineItemShippingDetails.
Be aware, that should a line item reference an address under itemShippingAddresses, this address cannot be deleted.
In this case, the line item shipping details have to first be updated to have the reference removed.
Only when this has occurred will the shipping address deletion be successful.
Example of a line item shipping address:
It is possible to tie multiple shipping addresses to one line item. If e.g. a cart contains 1000 customized paper bags and they have to be shipped across 10 point-of-sale locations, each receiving 100 paper bags, this is achieved by specifying the sub-quantities of the line item quantity for the different addresses.
Example of a line item with multiple shipping addresses:
When setting the line item shipping address, there is no enforcement that the sum of the shipping address quantities equal the line item quantity. This allows the shipping addresses to be gathered and added to the cart in a piecemeal way. However, as a help to ensure data integrity, a line item boolean called valid exists in order to determine whether the sum of the shipping address quantities add up to be equal to the line item quantity. A cart is still considered valid even though valid is false. However, when the cart is prompted for order creation, all valid flags has to be true. Otherwise, the order creation will be rejected.
Example of a line item with multiple shipping addresses where valid is false:
Shipping Rate and Tax Rates
It is important to be aware that the cart still only uses one shipping address for determining the eligible shipping methods and their shipping rates as well as the tax rates that are applied to line items.
The address for this is the one found in the cart’s shippingAddress property.
When line item level shipping addresses are needed, the address found under shippingAddress must also be part of itemShippingAddresses.
shippingAddress is the address that controls everything in relation to the cart’s shipping info property as well the tax rate for a line item
itemShippingAddresses is the complete set of addresses that line items can be associated with
Shipping vs. Delivery
There is a natural connection between the line item shipping addresses and the deliveries of the order.
However, we differentiate conceptually between the shipping addresses of the cart and the delivery addresses of the order.
The shipping addresses captured during checkout represent the request of the customer on where the individual items should be shipped.
The delivery data captured for the order is how the order was actually fulfilled.
Thus, the delivery information is not automatically set on the order based on which shipping addresses are set on the cart.
You can choose to keep these one to one, but this has to be posted actively by you to the order.
The resulting cart will contain the request to have the one line item split into different destinations.
Setting the shipping address quantity when managing a line item
In order to minimize the number of cart updates, it is also possible to set the line item shipping addresses alongside the line item update actions AddLineItem and RemoveLineItem.
Imagine you have a cart with itemShippingAddresses set:
Then you can use the update action AddLineItem to set the line item quantity and shipping details in one take:
The resulting cart will have a new line item with the shipping details set:
The update action RemoveLineItem can also be used to reduce the
quantities of the line item and the shipping details. Be aware that the field to declare how much sub-quantities need
to be removed is called shippingDetailsToRemove and not shippingDetails.
The resulting cart:
The update action ChangeLineitemQuantity
does not support changing the shipping details because an empty value could either be interpreted as an instruction to have them removed or to let them be untouched.
Consequently, a combination of ChangeLineitemQuantity
and SetLineItemShippingDetails is necessary to update
the quantities with absolute values.