Multiple Shipping Addresses and Methods
With Composable Commerce you have multiple ways of arranging shipping to different addresses. In this tutorial, you will learn when to use either multiple shipping addresses or multiple Shipping Methods for specific use cases.
Multiple shipping addresses are useful when you can deliver all items using a single Shipping Method. For example, a customer wishes to ship three items in their Order to three separate addresses, all using express delivery.
Multiple Shipping Methods are useful when you want to offer your customers more than one fulfillment method for their items in the same Order. For example, a customer wants to collect some items in person, and have the rest sent by express delivery. Another use case is when you need to mail some items of an Order using standard delivery and others using express delivery.
When shipping to multiple addresses, it's important to familiarize yourself with how tax calculation is handled by Composable Commerce.
In this tutorial, we'll use a Project that has been pre-configured with sample data. The option of using sample data is available to you when you initially set up your Project in the Merchant Center.
To follow the tutorial steps, you should have the following:
- A commercetools Composable Commerce Project that uses the pre-configured sample data
- Access to the Merchant Center
To reduce the length of example JSON responses, some fields that are not relevant to this tutorial have been removed or replaced with
Using multiple shipping addresses
In this example, a customer is ordering three items as gifts and wants to ship each item to a different friend. To accomplish this, we will create a Cart, add shipping addresses, and then set the shipping details of the individual Line Items.
After you've created your Cart, check the response and take note of the
id value of the Line Item (
lineItems.id). Later, we'll use this value to set the LineItem's shipping details.
Next, we need to add our three shipping addresses to the Cart, each with a unique
key, using the Add ItemShippingAddress update action. This update action adds the addresses to the Cart's
itemShippingAddresses property, which serves as the complete set of addresses available for use by the Cart.
Set the shipping details of Line Items
Now that our addresses are present in the Cart's
itemShippingAddresses field, we can assign them to the individual Line Items using the Set LineItemShippingDetails update action.
Since the customer is buying the same item three times, this update action sets the quantity to be sent to each address, identified by their unique
In the following update action, you must replace the
lineItemId value with the
lineItems.id value that you received during Cart creation.
After associating our shipping address and quantity to the Line Item, our Cart looks like this:
When you use the default ShippingMode
Single, you must set the
shippingAddress field directly on the Cart. In this case, the
shippingAddress determines the Tax Rate applied to each Line Item and the shipping rate. To do this, use the Set Shipping Address update action.
At this point, you can create an Order from the Cart.
For more information on how Composable Commerce calculates tax using the
shippingAddress field, see Cart tax rate selection.
Using multiple Shipping Methods
In the following example, a customer is ordering a coffee table, a rug, and a teapot from a Scandinavian furniture company.
Based on the customer's delivery preferences as well as the weight, availability, and insurance requirements, the order will be dispatched as follows:
- The coffee table will be picked up by the customer directly from the store.
- The rug will sent through the regular postal service.
- The teapot will be sent through an express delivery service.
Create the Shipping Methods
First, we need to create three Shipping Methods with the following names and keys. Later, these keys will be used as the
shippingKey in update actions.
|Shipping method name
|Collect in store
|Next day delivery
Using the Merchant Center, follow these steps for each Shipping Method:
- Go to Project settings > Shipping methods.
- Click Add shipping method.
- Add a Shipping method name, Key, and select a Tax category.
- Click Add zone, and select EU and UK from the zone dropdown.
- Click Add currency-specific rates and enter a fictitious shipping rate amount in EUR.
- Click Create shipping method.
We set the ShippingMode to
Multiple (the default value is
Single) because we are using more than one fulfillment method. Also, we add an address to the
itemShippingAddresses that contains a unique key. This address and key combination is used later to define the shipping details of our individual Line Items.
Add Shipping Methods to the Cart
Next, add the Shipping Methods to the Cart with the Add Shipping Method update action. You will need to specify a
shippingAddress for each Shipping Method defined inside the update action. We recommend that you provide a
key for the
shippingAddress that matches the
key found in the corresponding address listed in
shippingAddress is used later to calculate tax for any associated Line Item(s), or sub-quantities of a Line Item.
The following example requires the project specific
id for each Shipping Method. Use the Get a ShippingMethod by Key endpoint to retrieve the
id for each of the Shipping Methods that you previously created, then update the example accordingly.
Associate Line Items with Shipping Methods
Finally, we need to assign a Shipping Method to each Line Item. To do this, use the Set LineItemShippingDetails update action.
addressKeylinks the Line Item to an address found in the Cart's
shippingMethodKeylinks the Line Item to a specific Shipping Method.
In the following example, set the
lineItemId value to match the respective
id values in the
lineItems array from when you created the Cart.
With each Line Item now associated with a fulfillment address and Shipping Method, you can proceed to create an Order from the Cart.