Understand REST support for split shipping

To support the split shipping feature, updates have been made to the Profile and Orders resources in the Store REST API.

These resources contain endpoints for managing shopper profiles and orders, respectively.

• For the Profile resources, support has been added for an alias property to identify addresses in the address book.
• For the Orders endpoints, support has been added for multiple shipping groups, in the form of a shippingGroups array, and for an alias property to identify the addresses contained in those shipping groups. Each of the Orders endpoints that take detailed order or cart information in their request payload support the shippingGroups array. All of the Orders endpoints that return detailed order information will return a shippingGroups array in the response as long as there are cart items associated with the shipping groups. If none of the shipping groups for a cart or order have cart items associated with them then the shippingGroups array is suppressed in the endpoint response. This will typically be the case for persisted carts (incomplete orders) that existed in the order repository before the split shipping feature was deployed.

Understand the shippingGroups array

The shippingGroups array is supported in request and response payloads when appropriate. In request payloads, it is optional. In response payloads, it is returned as long as item relationships exist for one or more shipping groups in the cart/order. Each object in the shippingGroups array holds information about:

• The shipping address (shippingAddress object) for the shipping group. This shippingAddress object has an alias property that identifies the address.
• The shipping method (shippingMethod object) for the shipping group.
• The item relationships (items array) for the shipping group.
• The unique ID of the shipping group (shippingGroupId), if known.

Existing shippingAddress and shippingMethod properties

Prior to the introduction of the split shipping feature, the Store API endpoints only supported a single shipping group. All items in the cart inherently belonged to that shipping group though the relationship between shipping group and cart items was not established in the order repository until the order was submitted. To that end, the pricing and order-related endpoints supported specification of the shipping address and shipping method for the default shipping group, via the shippingAddress and shippingMethod properties, in the request and response payloads. For backwards compatibility these properties continue to be supported in the request and response payloads with the caveats described below.

In request payloads, the shippingAddress and shippingMethod properties are:

• Ignored if the shippingGroups array is specified.
• Used to set the shipping address and method of the first shipping group in the shippingGroups array when the shippingGroups array is not explicitly specified.

In response payloads, the shippingAddress and shippingMethod properties refer to the shipping address and shipping method of the first shipping group in the shippingGroups array.