Cart Transform Function API overview

The RunInput object is the complete schema that your function can receive as input.

For a list of fields that the Cart Transform API's RunInput object accepts, refer to RunInput.

Use the RunInput GraphQL query to specify the data that's required to inform the logic in your cart transform function. It is common to use cart line attributes or metafields to pass custom data in to the function using the RunInput query.

For example, you can write a cart transform function that adds an add-on extended warranty to a product when a customer opts-in by adding the product to the cart.

Use the cart line attribute (also known as a cart line property) that's created by the storefront when the cart line is added to determine whether or not to include the following:

• The warranty
• A metafield on the product to store the cost of the warranty as a percentage of the original product price
• A metafield that's stored on the cart transform itself, to store the ID of the product variant that represents the warranty product

The following example shows the resulting input to the query:

The FunctionRunResult 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: Specifies the components of an item and applies a price adjustment. For example, Skin care kit is expanded into 2x Face mask and 1x Cream.
• MergeOperation: Enables merging items together into a bundle by specifying the bundle's product parent. For example, the items 1x Burger, 1x Drink, and 2x Fries can be combined into the Meal Kit product, resulting in one item (Meal Kit) with three components.
• UpdateOperation: Enables overrides of item properties by specifying a new title, price, or image. This operation is only available to shops on a Plus plan or a Development store plan.

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.

• Multiple update operations targeting the same cart line: The first update operation in the list is executed, and all other update operations for the same cart line are discarded.

To activate your function, create a cartTransform object on the store where you installed your app using the cartTransformCreate mutation.

1. Install the Shopify GraphiQL app on your store and select the write_cart_transforms and write_products access scopes.

2. In the GraphiQL app, select the Admin API and the 2024-01 API version.

3. Find the ID of your function by executing the following query:

   The result contains a node with your function's ID:

4. Run the following mutation with the ID of your function:

   You should receive a GraphQL response that includes the ID of the new cartTransform object.

The following example demonstrates how you can use an update operation to provide a new title, image, and price for the cart line.

• Line item overrides

The following example demonstrates how you can use an expand operation to add an extended warranty.

You can update the title to show that the warranty is included, and add two cart items, one for the TV, and one for the warranty, each with their own fixed price.

This displays in the checkout as a bundle with the title "Awesome TV with Warranty" for $1150.00 with two child components, the TV and the warranty.

• Bundles: pricing per component
• Optional add-on products

The following example demonstrates how you can use a merge operation to combine multiple food items into a bundled meal with a price adjustment.

The Cart Transform API supports adjustments that decrease the price percentage as part of 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 sum of the components' fixedPricePerUnit, or the bundle product price, plus the adjustment, if present.

Expand operations allow adjustments to the price of each individual component in the bundle.

This can be done by providing a price on the expandedCartItems in the ExpandOperation.

When not providing a fixed price per unit on Expand operations, 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 10
• unit_price: $20, quantity: 2, id: 2 # weight 40
• unit_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

Title and image overrides are visible on different surfaces, such as cart, checkout, email, and order notification emails.

To see title overrides that Cart Transform functions make on a cart, cart notifications, or order notification emails, you need to make changes to your themes. Use item.title for cart or line.title for order notification emails to show the new title.

The following scenarios are considered as invalid:

expand operations:

• One of the component quantities is less than 0.
• The line to be expanded doesn't exist.
• One of the component variant IDs doesn't exist.
• Both ExpandedItem.Price and PriceAdjustment are returned in the operation.
• One of the components is given a price less than 0.
• Some of the components have a customized price and others don't.

merge operations:

• The merge operation contains an invalid quantity for the children (less than 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.

update operations:

• The operation includes a price < 0.
• The line to be updated doesn't exist.
• The operation targets a line that is going to be expanded or merged.
• The shop is not on a Plus plan or a Development store plan.

The following tables provide a complete list of errors that can occur when running your function.