Introduction
Use this tutorial when you already know which shipping model you need and want the full request and response sequence. It covers two worked recipes: one for sending items in a Cart to multiple addresses with a single Shipping Method, and one for combining multiple Shipping Methods in the same Cart. The examples follow concrete use cases so that you can adapt the API flow to your own implementation.
Learn more about implementing shipping information handling as part of a custom checkout flow in our self-paced Implement a custom checkout module.
This tutorial covers two patterns:
- Use
Singlewhen one cart-level shipping and tax context is enough for all item-level addresses. - Use
Multiplewhen Line Items need different Shipping Methods or different country or regional contexts.
Prerequisites
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
For conceptual guidance on choosing between these patterns, see Shipping and Delivery Overview.
To reduce the length of example JSON responses, some fields that are not relevant to this tutorial have been removed or replaced with
// ..Use cases
Use multiple shipping addresses
In this example, a customer is ordering three items as gifts and wants to ship each item to a different friend in Germany. To accomplish this, we will create a Cart, add shipping addresses, and then set the shipping details of the individual Line Items.
Create Cart
To create a Cart, we'll use the following CartDraft containing a single Line Item using the
sku of a ProductVariant, and a quantity set to three.{
"type": "Cart",
"id": "926f58d2-b6b3-447c-8988-c55fc2d51ffe",
"version": 1,
"currency": "EUR",
"key": "multiple-addresses",
"lineItems": [
{
"sku": "CCH-093",
"price": {
"id": "852fcca4-c1ec-442a-93cf-46bc01d2b883",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 1995,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 3,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-02-16T07:39:02.919Z",
"lastModifiedAt": "2023-02-16T07:39:02.919Z",
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 39600,
"fractionDigits": 2
},
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 39600,
"fractionDigits": 2
},
"country": "DE",
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"deleteDaysAfterLastModification": 90,
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [],
"totalLineItemQuantity": 3
}
After you've created your Cart, check the response and take note of the
id value of the Line Item (lineItems[0].id). Later, we'll use this value to set the LineItem's shipping details.Add addresses
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.In this example, all three addresses are in Germany because the Cart uses the default
Single ShippingMode. In Single mode, the Cart uses one shipping and tax context through its shippingAddress. If the items need to ship to addresses in different countries or regions, use Multiple instead. In that setup, you can still reuse the same Shipping Method by adding it to the Cart more than once and assigning each entry to the relevant item.{
"version": 1,
"actions": [
{
"action": "addItemShippingAddress",
"address": {
"key": "friend-1",
"streetName": "Street Name",
"streetNumber": "16",
"city": "Munich",
"country": "DE"
}
},
{
"action": "addItemShippingAddress",
"address": {
"key": "friend-2",
"streetName": "Street Name",
"streetNumber": "21",
"city": "Hamburg",
"country": "DE"
}
},
{
"action": "addItemShippingAddress",
"address": {
"key": "friend-3",
"streetName": "Street Name",
"streetNumber": "52",
"city": "Berlin",
"country": "DE"
}
}
]
}
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
key.In the following update action, you must replace the
lineItemId value with the lineItems[0].id value that you received during Cart creation.{
"version": 5,
"actions": [
{
"action": "setLineItemShippingDetails",
"lineItemId": "{lineItemId}",
"shippingDetails": {
"targets": [
{
"addressKey": "friend-1",
"quantity": 1
},
{
"addressKey": "friend-2",
"quantity": 1
},
{
"addressKey": "friend-3",
"quantity": 1
}
]
}
}
]
}
After associating our shipping address and quantity to the Line Item, our Cart looks like this:
{
"type": "Cart",
"id": "994449d0-85d5-4afe-b32e-45ed309e0d47",
"version": 7,
"createdAt": "2023-10-30T10:13:23.312Z",
"lastModifiedAt": "2023-10-30T10:56:26.201Z",
"lastModifiedBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"createdBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"key": "multiple-addresses-5",
"lineItems": [
{
"id": "585a3207-a72d-421d-a963-41521d4f7b37",
"productId": "10097630-6171-43b3-bdda-a64c4b63dffc",
"productKey": "charcoal-chair",
"name": {
// ..
},
"productType": {
// ..
},
"productSlug": {
//...
},
"variant": {
"id": 1,
"sku": "CCH-093",
"prices": [
{
"id": "ca0208f7-361a-42b4-8375-b7ab4649e367",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 9900,
"fractionDigits": 2
},
"country": "DE",
"discounted": {
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 8415,
"fractionDigits": 2
},
"discount": {
"typeId": "product-discount",
"id": "d46c042e-aa81-405e-bc36-92058cb06f0c"
}
}
}
],
"images": []
"attributes": []
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 100,
"version": 1,
"id": "8d27b91c-763a-4aed-833c-aae9dcc27baf"
}
},
"price": {
"id": "ca0208f7-361a-42b4-8375-b7ab4649e367",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 9900,
"fractionDigits": 2
},
"country": "DE",
"discounted": {
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 8415,
"fractionDigits": 2
},
"discount": {
"typeId": "product-discount",
"id": "d46c042e-aa81-405e-bc36-92058cb06f0c"
}
}
},
"quantity": 3,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-02-16T07:39:02.919Z",
"lastModifiedAt": "2023-10-30T10:56:26.181Z",
"state": [
{
"quantity": 3,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 25245,
"fractionDigits": 2
},
"taxedPricePortions": [],
"shippingDetails": {
"targets": [
{
"addressKey": "friend-1",
"quantity": 1
},
{
"addressKey": "friend-2",
"quantity": 1
},
{
"addressKey": "friend-3",
"quantity": 1
}
],
"valid": true
}
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 25245,
"fractionDigits": 2
},
"country": "DE",
"shippingMode": "Single",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"deleteDaysAfterLastModification": 90,
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [
{
"streetName": "Street Name",
"streetNumber": "16",
"city": "Munich",
"country": "DE",
"key": "friend-1"
},
{
"streetName": "Street Name",
"streetNumber": "21",
"city": "Hamburg",
"country": "DE",
"key": "friend-2"
},
{
"streetName": "Street Name",
"streetNumber": "52",
"city": "Berlin",
"country": "DE",
"key": "friend-3"
}
],
"totalLineItemQuantity": 3
}
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.Because
Single mode uses one cart-level shipping and tax context, this pattern works only when the item-level addresses stay within that same country or regional context. If the items need to ship to different countries or regions, switch to Multiple mode and add the same Shipping Method to the Cart more than once if you need to reuse the same fulfillment option.At this point, you can create an Order from the Cart.
For the reference explanation of shipping tax behavior, see Shipping and Delivery Overview and Cart tax rate selection.
Use 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 be 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. Add each of them to the "EU and UK" Zone, and add currency-specific rates with a fictitious shipping rate amount in EUR. Later, these keys will be used as the
shippingKey in update actions.| Shipping method name | Key |
|---|---|
| Collect in store | collect-in-store |
| Postal service | postal-service |
| Next day delivery | next-day-delivery |
To create these Shipping Methods in the Merchant Center, do the following:
- Go to Settings > Project settings and click the Shipping methods tab.
- Follow the steps in Add a Shipping Method for each name and key in the table. For this example, use the same Tax Category for all three Shipping Methods, add the EU and UK Zone, add a currency-specific rate in EUR, and save each Shipping Method before continuing.
Create Cart
Next, create a Cart that contains all three items with the following CartDraft. The Line Items are added using the
sku of each ProductVariant.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.{
"key": "multiple-methods",
"currency": "EUR",
"country": "DE",
"lineItems": [
{
"sku": "WTP-09", // Willow Teapot
"quantity": 1
},
{
"sku": "AAR-34", // Aria Rug
"quantity": 1
},
{
"sku": "ADCT-01", // Art Deco Coffee Table
"quantity": 1
}
],
"shippingMode": "Multiple",
"itemShippingAddresses": [
{
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
]
}
{
"type": "Cart",
"id": "c4061cd2-1d27-43bf-914a-137b0e98eb7a",
"version": 1,
"createdAt": "2023-10-30T13:49:40.287Z",
"lastModifiedAt": "2023-10-30T13:49:40.287Z",
"lastModifiedBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"createdBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"key": "multiple-methods",
"lineItems": [
{
"id": "2d5db73b-6f16-4f03-aba8-17c30446045b",
"productId": "b9aad728-e8a2-4f14-a890-e6ee800a6ec9",
"productKey": "willow-teapot",
"name": {
"en-US": "Willow Teapot",
"en-GB": "Willow Teapot",
"de-DE": "Teekanne >Willow<"
},
"productType": {
// ..
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "WTP-09",
"prices": [
{
"id": "0ad9b838-410c-4b1c-8555-3432841f60ae",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"attributes": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 100,
"version": 1,
"id": "d01e7ce9-0b4b-4e40-bd45-ab520e77e233"
}
},
"price": {
"id": "0ad9b838-410c-4b1c-8555-3432841f60ae",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"taxedPricePortions": []
},
{
"id": "8aee5e05-1a22-4f5e-bbc5-da2e7ab9fadf",
"productId": "59d954eb-f578-4eb4-aa42-7883382dbeea",
"productKey": "aria-rug",
"name": {
"en-US": "Aria Rug",
"en-GB": "Aria Rug",
"de-DE": "Teppich \"Aria\""
},
"productType": {
// ..
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "AAR-34",
"prices": [
{
"id": "856b261c-90dd-44be-a019-430085148268",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"attributes": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 100,
"version": 1,
"id": "54d301e9-e3fe-42fc-80f9-45f5969c6d82"
}
},
"price": {
"id": "856b261c-90dd-44be-a019-430085148268",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"taxedPricePortions": []
},
{
"id": "3bf52dbd-52e7-4d69-b314-1e5828725c6c",
"productId": "7310bf2f-94b4-437e-b5aa-58dcddac4b26",
"productKey": "art-deco-coffee-table",
"name": {
"en-US": "Art Deco Coffee Table",
"en-GB": "Art Deco Coffee Table",
"de-DE": "Couchtisch im Art-Deco-Stil"
},
"productType": {
// ..
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "ADCT-01",
"prices": [
{
"id": "8dd144f2-ff8a-4be8-851e-01318895cdfa",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"attributes": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 90,
"version": 1,
"id": "7c0b963f-0664-46a7-8d14-696170a5e2d9"
}
},
"price": {
"id": "8dd144f2-ff8a-4be8-851e-01318895cdfa",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 333398,
"fractionDigits": 2
},
"country": "DE",
"shippingMode": "Multiple",
"shipping": [],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"deleteDaysAfterLastModification": 90,
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [
{
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
],
"totalLineItemQuantity": 3
}
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 itemShippingAddresses. The 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.{
"version": 1,
"actions": [
{
"action": "addShippingMethod",
"shippingKey": "postal-service",
"shippingMethod": {
"id": "{shippingMethod.id}",
"typeId": "shipping-method"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
},
{
"action": "addShippingMethod",
"shippingKey": "next-day-delivery",
"shippingMethod": {
"id": "{shippingMethod.id}",
"typeId": "shipping-method"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
},
{
"action": "addShippingMethod",
"shippingKey": "collect-in-store",
"shippingMethod": {
"id": "{shippingMethod.id}",
"typeId": "shipping-method"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
}
]
}
{
"type": "Cart",
"id": "c4061cd2-1d27-43bf-914a-137b0e98eb7a",
"version": 7,
"createdAt": "2023-10-30T13:49:40.287Z",
"lastModifiedAt": "2023-10-30T14:16:14.278Z",
"lastModifiedBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"createdBy": {
"clientId": "JPaMsuS9_y_zjD4GaQf1jcja",
"isPlatformClient": false
},
"key": "multiple-methods",
"lineItems": [
{
"id": "2d5db73b-6f16-4f03-aba8-17c30446045b",
"productId": "b9aad728-e8a2-4f14-a890-e6ee800a6ec9",
"productKey": "willow-teapot",
"name": {
"en-US": "Willow Teapot",
"en-GB": "Willow Teapot",
"de-DE": "Teekanne >Willow<"
},
"productType": {
// ..
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "WTP-09",
"prices": [
{
"id": "0ad9b838-410c-4b1c-8555-3432841f60ae",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 100,
"version": 1,
"id": "d01e7ce9-0b4b-4e40-bd45-ab520e77e233"
}
},
"price": {
"id": "0ad9b838-410c-4b1c-8555-3432841f60ae",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 899,
"fractionDigits": 2
},
"taxedPricePortions": []
},
{
"id": "8aee5e05-1a22-4f5e-bbc5-da2e7ab9fadf",
"productId": "59d954eb-f578-4eb4-aa42-7883382dbeea",
"productKey": "aria-rug",
"name": {
"en-US": "Aria Rug",
"en-GB": "Aria Rug",
"de-DE": "Teppich \"Aria\""
},
"productType": {
// ..
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "AAR-34",
"prices": [
{
"id": "856b261c-90dd-44be-a019-430085148268",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"attributes": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 100,
"version": 1,
"id": "54d301e9-e3fe-42fc-80f9-45f5969c6d82"
}
},
"price": {
"id": "856b261c-90dd-44be-a019-430085148268",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 12499,
"fractionDigits": 2
},
"taxedPricePortions": []
},
{
"id": "3bf52dbd-52e7-4d69-b314-1e5828725c6c",
"productId": "7310bf2f-94b4-437e-b5aa-58dcddac4b26",
"productKey": "art-deco-coffee-table",
"name": {
"en-US": "Art Deco Coffee Table",
"en-GB": "Art Deco Coffee Table",
"de-DE": "Couchtisch im Art-Deco-Stil"
},
"productType": {
"typeId": "product-type",
"id": "18d201f7-86a6-4584-b902-567dec61c42e",
"version": 1
},
"productSlug": {
// ..
},
"variant": {
"id": 1,
"sku": "ADCT-01",
"prices": [
{
"id": "8dd144f2-ff8a-4be8-851e-01318895cdfa",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"country": "DE"
}
],
"images": [],
"attributes": [],
"assets": [],
"availability": {
"isOnStock": true,
"availableQuantity": 90,
"version": 1,
"id": "7c0b963f-0664-46a7-8d14-696170a5e2d9"
}
},
"price": {
"id": "8dd144f2-ff8a-4be8-851e-01318895cdfa",
"value": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"country": "DE"
},
"quantity": 1,
"discountedPricePerQuantity": [],
"perMethodTaxRate": [],
"addedAt": "2023-10-30T13:49:40.278Z",
"lastModifiedAt": "2023-10-30T13:49:40.278Z",
"state": [
{
"quantity": 1,
"state": {
"typeId": "state",
"id": "58f809e9-c73b-483a-ba78-913e77526311"
}
}
],
"priceMode": "Platform",
"lineItemMode": "Standard",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 320000,
"fractionDigits": 2
},
"taxedPricePortions": []
}
],
"cartState": "Active",
"totalPrice": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 339398,
"fractionDigits": 2
},
"country": "DE",
"shippingMode": "Multiple",
"shipping": [
{
"shippingKey": "postal-service",
"shippingInfo": {
"shippingMethodName": "Postal service",
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 1000,
"fractionDigits": 2
},
"shippingRate": {
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 1000,
"fractionDigits": 2
},
"tiers": []
},
"taxRate": {
"name": "Standard VAT for Germany",
"amount": 0.19,
"includedInPrice": true,
"country": "DE",
"id": "_eWbB-Un",
"key": "vat-standard-de",
"subRates": []
},
"taxCategory": {
"typeId": "tax-category",
"id": "2bd2720c-4ae5-477a-9ffa-5efca176f93d"
},
"deliveries": [],
"shippingMethod": {
"typeId": "shipping-method",
"id": "a50c1b60-5414-4676-af83-8b069cc88c91"
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 840,
"fractionDigits": 2
},
"totalGross": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 1000,
"fractionDigits": 2
},
"totalTax": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 160,
"fractionDigits": 2
}
},
"shippingMethodState": "MatchesCart"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
},
{
"shippingKey": "next-day-delivery",
"shippingInfo": {
"shippingMethodName": "Next day delivery",
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 5000,
"fractionDigits": 2
},
"shippingRate": {
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 5000,
"fractionDigits": 2
},
"tiers": []
},
"taxRate": {
"name": "Standard VAT for Germany",
"amount": 0.19,
"includedInPrice": true,
"country": "DE",
"id": "_eWbB-Un",
"key": "vat-standard-de",
"subRates": []
},
"taxCategory": {
"typeId": "tax-category",
"id": "2bd2720c-4ae5-477a-9ffa-5efca176f93d"
},
"deliveries": [],
"shippingMethod": {
"typeId": "shipping-method",
"id": "becb558d-4fe1-4735-a4a5-325badccd84f"
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 4202,
"fractionDigits": 2
},
"totalGross": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 5000,
"fractionDigits": 2
},
"totalTax": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 798,
"fractionDigits": 2
}
},
"shippingMethodState": "MatchesCart"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
},
{
"shippingKey": "collect-in-store",
"shippingInfo": {
"shippingMethodName": "Collect in store",
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"shippingRate": {
"price": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"tiers": []
},
"taxRate": {
"name": "Standard VAT for Germany",
"amount": 0.19,
"includedInPrice": true,
"country": "DE",
"id": "_eWbB-Un",
"key": "vat-standard-de",
"subRates": []
},
"taxCategory": {
"typeId": "tax-category",
"id": "2bd2720c-4ae5-477a-9ffa-5efca176f93d"
},
"deliveries": [],
"shippingMethod": {
"typeId": "shipping-method",
"id": "e45f7b5a-209b-4cd9-a3bd-199f7352781c"
},
"taxedPrice": {
"totalNet": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"totalGross": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
},
"totalTax": {
"type": "centPrecision",
"currencyCode": "EUR",
"centAmount": 0,
"fractionDigits": 2
}
},
"shippingMethodState": "MatchesCart"
},
"shippingAddress": {
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
}
],
"customLineItems": [],
"discountCodes": [],
"directDiscounts": [],
"inventoryMode": "None",
"taxMode": "Platform",
"taxRoundingMode": "HalfEven",
"taxCalculationMode": "LineItemLevel",
"deleteDaysAfterLastModification": 90,
"refusedGifts": [],
"origin": "Customer",
"itemShippingAddresses": [
{
"street": "Frankfurter Tor 4",
"city": "Berlin",
"postalCode": "10243",
"country": "DE",
"key": "address-key-berlin"
}
],
"totalLineItemQuantity": 3
}
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.
- The
addressKeylinks the Line Item to an address found in the Cart'sitemShippingAddressesfield. - The
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.{
"version": 1,
"actions": [
{
"action": "setLineItemShippingDetails",
"lineItemId": "{lineItemId}",
"shippingDetails": {
"targets": [
{
"addressKey": "address-key-berlin",
"shippingMethodKey": "collect-in-store",
"quantity": 1
}
]
}
},
{
"action": "setLineItemShippingDetails",
"lineItemId": "{lineItemId}",
"shippingDetails": {
"targets": [
{
"addressKey": "address-key-berlin",
"shippingMethodKey": "postal-service",
"quantity": 1
}
]
}
},
{
"action": "setLineItemShippingDetails",
"lineItemId": "{lineItemId}",
"shippingDetails": {
"targets": [
{
"addressKey": "address-key-berlin",
"shippingMethodKey": "next-day-delivery",
"quantity": 1
}
]
}
}
]
}
With each Line Item now associated with a fulfillment address and Shipping Method, you can proceed to create an Order from the Cart.
For the reference behavior behind this flow, see Shipping and Delivery Overview.