Multiple Shipments API Overview

This topic outlines how to use the API to manage multiple shipments.

Introduction to Multiple Shipments

Shipping to multiple addresses allows shoppers to send items within an order to different destinations, or to use a combination of fulfillment methods for the items, such as direct ship, in-store pickup, or gift card (digital) delivery. For example, a shopper can purchase three items and choose to send those items to three different destinations. Each destination the shopper chooses to send items to can use a different fulfillment method, such as standard versus expedited shipping. In addition, shoppers can choose to direct ship a subset of order items, while marking other items for in-store pickup or gift card delivery.

Currently, the ability to ship to multiple addresses within one order has several limitations. For example, this feature only supports Auth on Order Submit and Capture on Fulfillment as credit card authorization/capture methods. It does not support Auth and Capture on Order Submit as an authorization method, nor does it support Pay with Amazon as a payment method. In addition, enabling this feature requires extensive theme work that you can't easily reverse (if you later choose to disable the feature).

To learn more about this feature, including its limitations, refer to the Ship to Multiple Addresses topic.

API Structure

The multiple shipments feature applies on the site level (rather than applying to all sites in a tenant). On the theme side, sites with the feature enabled include modified themes with new order confirmation pages that allow shoppers to ship to multiple addresses and use different fulfillment methods. These sites also include new order confirmation emails to send to shoppers. On the API side, sites with the feature enabled take advantage of a new API resource called Checkout, which manages order items, their intended destinations, and their logical groupings prior to order submission.

Checkout Resource

During the checkout process, the API creates the Checkout resource to track a shopper's order items and their intended destinations. The Checkout resource is active until the shopper submits the order, at which point one or many orders are created based on the data contained in the Checkout resource.

The Checkout resource includes the GetCheckout and GetCheckouts operations, which let you read checkouts available on a site.

Important elements within the Checkout resource include the Destinations subresource and the Groupings collection, which help structure how orders generate after a shopper hits Submit.


Each order item contains a destination field that specifies where the item ships to. Direct ship items point to a physical address, digital items point to an email, and in-store pickup items point to a blank field. At the Checkout level, a Destinations collection specifies the full list of destinations for the checkout.


Groupings bundle items together that have the same fulfillment type and destination. Direct ship items going to the same destination are grouped together, in-store pickup items are grouped together, and gift card items are grouped together. For example, suppose a shopper adds six items to their cart. Items A and B are direct ship items to different destinations, Items C and D are in-store pickup items, and Items E and F are gift cards. The following groupings result (the exact order of grouping numbers is not important):

Grouping 1

Grouping 2

Grouping 3

Grouping 4

Order Creation Based on Groupings

After a shopper submits the order (finishing their checkout process), one or many Order resources are created based on the groupings. Groupings that contain direct ship items are placed within their own orders (because the items are shipping to distinct destinations). In-store pickup and gift card groupings are bundled into the first direct ship order created, if it exists (otherwise a new order is created and the groupings are placed within it).

For example, to visualize how orders are created based on groupings, take the same example where a shopper purchases six items. Items A and B are direct ship items to different destinations, Items C and D are in-store pickup items, and Items E and F are gift cards. In this case, two orders will be created based on the four aforementioned groupings, as follows:

Order 1

Order 2

Effect on Discounts, Shipping, and Payment

Because of the grouping and order breakdown for multiple shipments, order-level discounts apply at the shipment level that results from the order creation. For more information about the effect on discounts, and how you must be careful when creating discounts for a site that supports multiple shipments, refer to the Guides topic.

During checkout, the Shipping runtime adds common shipping method prices together across the multiple shipments that will result from the groupings, and displays the total price to the shopper on the confirmation page. After a shopper enters payment information and submits their order, payments are split according to the resulting orders.

Effect on Fraud Check

Fraud checks run on each order created after the shopper submits their checkout. For example, if an order with multiple shipments results in three orders generated, fraud checks run on all three orders individually.

Specify Different Shipment Methods for Items with the Same Destination

Currently, the API bundles direct ship items going to the same destination into one grouping. This means that all items going to the same destination must use the same shipment method. If you want items going to the same destination to use different shipment methods, so that some items arrive faster than others, you need to use Arc.js. In the near future, you will have access to an Arc.js action that can further subdivide groupings, allowing you to implement finer control over shipment methods to the same destination (and other such customizations).