Overview of the concepts related to shipping and delivery of Orders in your Composable Commerce Project.
Shipping versus Delivery
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 as to where the individual items should be shipped.
- The delivery information captured for the Order represent how the Order is actually fulfilled.
Shipping addresses
Single
, you must set a shippingAddress
for the Cart before it can be converted into an Order.shippingAddress
field of the Cart determines the following:- The Shipping Methods that are available and their shipping rates
- The Tax Rate applied to each (Custom) Line Item and the shipping rate
shippingAddress
field, see Cart tax rate selection.Ship to a single address
Ship to multiple addresses
Single
on CartDraft. Once set, the ShippingMode
field can not be changed.shippingAddress
field of the Cart is used for taxation purposes and must be set in the CartDraft or with the Set Shipping Address update action.itemShippingAddresses
field, which contains the complete set of addresses available for use by the Cart.itemShippingAddresses
, this address can not be deleted. To delete the address, you must first update the Line Item shipping details and remove the reference.key
that is unique to the Cart. The key
is required when assigning the respective shipping address to a Line Item in the ItemShippingTarget (used with the
Set LineItem ShippingDetails update action).Shipping sub-quantities to different addresses
You can also ship sub-quantities of a Line Item to different addresses.
100
paper bags that must be shipped to three point-of-sale locations, you can specify the sub-quantities of the LineItem quantity
for each address.Shipping address | Sub-quantity |
---|---|
address_1 | 10 |
address_2 | 40 |
address_3 | 50 |
{
"id": "e38a6110-fc74-4095-bde5-9898375e6904",
"productId": "ed7f5333-6f5d-4d07-a44f-2a24885bae0c",
"name": {
"en": "Branded paper bag"
},
"variant": {
"id": 1,
"sku": "sku_4002"
},
"price": {
"value": {
"currencyCode": "USD",
"centAmount": 4200
},
"id": "278af989-688a-4b60-a26f-bee2a2e40920"
},
"quantity": 100,
"priceMode": "Platform",
"totalPrice": {
"currencyCode": "USD",
"centAmount": 630000
},
"lineItemMode": "Standard",
"shippingDetails": {
"targets": [
{
"addressKey": "address_1",
"quantity": 10
},
{
"addressKey": "address_2",
"quantity": 40
},
{
"addressKey": "address_3",
"quantity": 50
}
],
"valid": true
}
}
quantity
. This allows the shipping addresses to be gathered and added to the Cart in a piecemeal way. However, to ensure data integrity, a boolean field called valid
exists to determine whether the sum of the shipping address quantities equal the LineItem quantity
.valid
is false
. However, during Order creation, all valid
flags must be true
, otherwise the Order creation will be rejected.Shipping Methods
isDefault
boolean inside an individual Shipping Method. When a Shipping Method has isDefault
set to true
, it appears as the first item in the array when retrieving matching Shipping Methods. This flag does not automatically apply the Shipping Method to Carts; instead, you can use it to identify which Shipping Method should be pre-selected during checkout.Single Shipping Method
Single
on CartDraft. Once set, the ShippingMode
field can not be changed.Single
, tax is calculated and applied to the contents of the Cart based on the address in the shippingAddress
field.Multiple Shipping Methods
Multiple
on CartDraft. For example, a customer wants to collect some items in person and have the rest sent by express delivery.To add and assign Shipping Methods, do the following:
-
Specify any shipping addresses to be used by the Line Items in your Cart. For new Carts, you can specify addresses in the
itemShippingAddresses
field on CartDraft. For existing Carts, you can use the Add ItemShippingAddress update action, which adds the addresses to theitemShippingAddresses
field. TheitemShippingAddresses
field is the complete set of addresses available for use by the Cart. -
Use the Add Shipping Method or Add Custom Shipping Method (for externally managed Shipping Methods) update action to add Shipping Methods to a Cart. In the update action, you need to specify a
shippingAddress
for the Shipping Method. We recommend that you provide akey
for theshippingAddress
that matches thekey
of the corresponding address listed initemShippingAddresses
. TheshippingAddress
is used later to calculate tax for any associated (Custom) Line Item(s), or sub-quantities of a (Custom) Line Item.
Both internal and external (outside Composable Commerce) Shipping Methods can coexist in a single Cart.
- Assign a Shipping Method to each Line Item using the Set LineItemShippingDetails update action.
- The LineItem's or CustomLineItem's
perMethodTaxRate
field contains the individual Tax Rates applied within a single Line Item together with the Shipping Methods assigned to it. This field is equivalent to thetaxRate
field when using the default ShippingModeSingle
. - The LineItem's or CustomLineItem's
taxedPricePortions
field contains individual taxed prices of each Shipping Method. This is automatically calculated whenperMethodTaxRate
is set.
Predicates
predicate
field directly on each Shipping Method.For example:
- Shipping Method "Express" should only be offered for Carts with Line Items that are eligible for express shipping.
- Shipping Method "Overnight" should not be offered to a certain segment of the customers.
- Shipping Method "Ground" is the only method available for Carts with bulky items weighing more than 10 kg.
- Shipping Method "Scandinavia" is the only method available for Carts in the Store for Sweden.
// matches a cart when at least one Line Item has the Custom Field attribute "eligible_for_express_shipping" set to TRUE
lineItemExists(attributes.eligible_for_express_shipping = true)
// matches a cart for all customer group except one
customerGroup.id != "f6a19a23-14e3-40d0-aee2-3e612fcb1bc7"
// matches a cart when at least one Line Item has the Custom Field attribute "bulky" set to TRUE and when at least one Line Item has the Custom Field attribute "weightInKilograms" set to a value greater than 10
lineItemExists(attributes.bulky = true) and lineItemExists(attributes.weightInKilograms > 10)
// matches a cart with Store key "sweden-store"
store.key = "sweden-store"
totalPrice > "100.00 USD"
will be applicable even if only $10 worth of goods is associated with it, so long as total Cart price satisfies the predicate. Similarly, this also applies to the Shipping Method's freeAbove
price.shippingMethodState
found under the Cart's ShippingInfo changes from MatchesCart
to DoesNotMatchCart
. If you attempt to create an Order from a Cart that has ShippingMethodState with DoesNotMatchCart
, the Order creation will be rejected.Shipping Rates
Fixed shipping rates
A fixed shipping rate is a rate assigned to a Shipping Method that never changes, even if the content or the conditions of a Cart is modified.
Tiered shipping rates
The alternative to fixed shipping rates is tiered shipping rates. This allows you to set shipping rates that increase or decrease, based on the tiers that you define. For example, you might want the shipping rate to decrease based on the Cart value, meaning the more money the customer is spending, the cheaper the shipping becomes.
- CartValueType: the shipping rate maps to the sum of all Line Item totals and Custom Line Item totals (after discounts have been applied).
- CartClassificationType: the shipping rate maps to an abstract Cart categorization expressed through a string (for example,
Light
,Medium
,Heavy
). - CartScoreType: the shipping rate maps to an abstract Cart categorization expressed through an integer (for example, a cart score or weight range).
shippingRateInput
on CartDraft which is used as look-up value to determine the shipping rate according to the defined tiers. If no value is set, or there is no tier for the value, the default shipping rate is used. An exception to this is when the ShippingRateInputType is set to CartValueType. In this case, the shipping rate is determined by the sum of all Line Item totals and Custom Line Item totals (via the totalPrice
field) after discounts have been applied.Define shipping tiers
tiers
within the ShippingRate object.The following examples illustrate tiered shipping rates for each input type.
CartValueType
In this example, the shipping rate gradually decreases until it becomes free of charge when the Cart value exceeds $100.
Shipping Rate Tier | Shipping Rate |
---|---|
Default | $4 |
> $50 | $3 |
> $75 | $2 |
> $100 | $0 |
CartClassificationType
Shipping Rate Tier | Shipping Rate |
---|---|
Default | $10 |
Medium | $25 |
Heavy | $50 |
CartScoreType
In this example, the score represents the total weight of the Cart expressed in grams. A Cart with a combined weight of 50 grams or less, will have a shipping rate of $1.75. As the weight increases, the shipping rate increases.
Shipping Rate Tier | Shipping Rate |
---|---|
Default | $1.75 |
> 50 | $2.50 |
> 100 | $4.75 |
> 500 | $7.25 |
> 1000 | $10.50 |
Shipping Rate Tier | Shipping Rate |
---|---|
Default | $2 |
> 5 | $3 |
> 15 | $6 |
> 25 | $8 |
> 35 | x - 30 |
Free shipping
To offer free shipping, use one of the following methods:
freeAbove
value on ShippingRateDraft. Alternately, you can set this value inside individual Shipping Methods using the Merchant Center.totalPrice
of the Cart (minus any previously added shipping costs) equals or exceeds the freeAbove
price.- If the (Custom) Line Items' prices do not include taxes, the
totalPrice
value is calculated from the net total price of the (Custom) Line Items. - If the (Custom) Line Items' prices include taxes, the
totalPrice
is calculated from the gross total price of the (Custom) Line Items.
target
property of the CartDiscountDraft to CartDiscountShippingCostTarget.Shipping rate calculation
The shipping rate is calculated when at least one of the following occurs:
- The
shippingRateInput
field on the Cart is updated. - The
shippingMethod
is updated on ShippingInfo. - The ShippingRateInputType is CartValueType and the total price of the Cart changes.
- The
freeAbove
free shipping threshold value exists and the total price of the Cart changes.
Tax calculation
Platform tax mode
shippingAddress
field is used for determining the eligible Shipping Methods and their shipping rates, as well as the tax rates that are applied to (Custom) Line Items and shipping rate.taxedShippingPrice
field represents the sum of taxed prices across all Shipping Methods.shipping
.External tax mode
External
and ExternalAmount
require the tax rate/amount to be manually set on each (Custom) Line Item and Shipping Method.Multiple
, with the added constraint that the rates/amounts must be present for each Shipping Method associated with a given (Custom) Line Item. Update actions SetLineItemTaxRate, SetLineItemTaxAmount, SetCustomLineItemTaxRate, and SetCustomLineItemTaxAmount contain a shippingKey
parameter that you can use to define which method/address combination the rate is referring.