Cart Transform API reference
The Cart Transform API enables you to expand cart line items and update the presentation of cart line items. The API includes two key objects: Input
and FunctionResult
.
The Input
object is the complete schema that your function can receive as input.
For a list of fields that the Cart Transform API's Input
object accepts, refer to Input.
The following example shows an input query:
The following example shows the resulting input to the query:
FunctionResult
Anchor link to section titled "FunctionResult"The FunctionResult
object is the shape of the function's output.
The output returns a list of cart operations, where each element can have one of the following values:
ExpandOperation
: Specify the components of an item and apply a price adjustment. For example,Skin care kit
is expanded into2x Face mask
and1 cream
.MergeOperation
: Enable merging items together into a bundle by specifying the bundle's product parent. For example, the items1x Burger
,1x Coke
, and2x Fries
can be combined into theMeal Kit
product, resulting in one item (Meal Kit
) with three components.
In the case where the function returns multiple operations and there's a collision, Shopify executes a subset of the operations using the following criteria:
Multiple expand operations targeting the same cart line: The first expand operation in the list is executed, and all other expand operations for the same cart line are discarded.
Multiple merge operations targeting the same cart line: The first merge operation in the list is executed, and all other merge operations for the same cart line are discarded.
Expand and merge operations targeting the same cart line: The expand operation is executed, and the merge operation is discarded.
The following example shows an input query:
The following function result uses all operations on the single Transform Cart API:
Bundles pricing
Anchor link to section titled "Bundles pricing"The Cart Transform API supports adjustments that decrease the price percentage Merge
and Expand
operations.
The bundle base price varies depending on the operation:
Merge
: The adjustment is based off of the components' price sum.Expand
: The adjustment is based off of the bundle product price.
This distinction enables the right price to display for Expand
on the product details page and in Liquid.
For example, to arrive at the final bundle price, you can employ a range of post-processing steps:
Merge
: The price is the sum of the components' price, plus the adjustment, if present.Expand
: The price is the bundle product price, plus the adjustment, if present.
Weight price algorithm
Anchor link to section titled "Weight price algorithm"The weight price algorithm allocates the bundle price to its component lines based on the weight of each component line. The weight of a component is the unit price multiplied by quantity, as unit price * quantity
.
The algorithm considers the item's price as if the item was bought individually and the quantity inside the bundle. For example, if a bundle has 10 t-shirts and 1 pair of shorts, and the shorts and t-shirt cost $5 if they were bought individually, then Shopify allocates more weight to the t-shirt.
The total weight of all component lines is then used to calculate the weight of each component line.
Amount to be allocated: $100
Component lines:
unit_price
: $10,quantity
: 1,id
: 1 # weight 10unit_price
: $20,quantity
: 2,id
: 2 # weight 40unit_price
: $30,quantity
: 3,id
: 3 # weight 90
Total weight: 140
Result:
- Component 1: $7.14 -> (10 / 140) * $100 = 7.14
- Component 2: $28.57 -> (40 / 140) * $100 = 28.57
- Component 3: $64.29 -> (90 / 140) * $100 = 64.29
Invalid operations
Anchor link to section titled "Invalid operations"Shopify discards merge operations when any of the following scenarios occur:
- The merge operation contains an invalid quantity for the children (< 0 or the quantity to merge is bigger than the line's quantity).
- The parent variant ID doesn't exist.
- One of the lines to be merged doesn't exist.
Shopify discards expand operations when any of the following scenarios occur:
- One of the component quantities is < 0.
- The line to be expanded doesn't exist.
- One of the component variant IDs doesn't exist.