Skip to main content

Add a customized bundle function

This guide shows you how to add a customized bundle using Shopify Functions.

What you'll learn

In this tutorial, you'll learn how to do the following tasks:

Anchor to RequirementsRequirements

  • You're using API version 2025-07 or higher for your function.

Anchor to Rust-specific requirementsRust-specific requirements

The following requirements are specific to Rust-based development with Shopify Functions.

  • You've installed Rust.

    On Windows, Rust requires the Microsoft C++ Build Tools. Make sure to select the Desktop development with C++ workload when installing the tools.

  • You've installed the wasm32-wasip1 target:

    Terminal

    rustup target add wasm32-wasip1

Anchor to Metafields versus line item propertiesMetafields versus line item properties

When you build custom bundles with cart transforms, you can store bundle data using metafields or line item properties. Choose metafields when you need secure, merchant-defined bundles with fixed compositions. Choose line item properties when you need flexible, buyer-customizable bundles, but ensure you implement proper validation and don't rely solely on the properties for critical business logic.

Metafields Line item properties
Best for Fixed bundles where the bundle composition is predetermined by the merchant Mix-and-match bundles where buyers can customize the bundle composition
Pros
  • More secure as metafield data cannot be modified by the browser
  • Bundles with a fixed-set of merchant defined components means you know exactly what each bundle contains and don't need to validate that the bundle contains permitted variants and quantities selected
  • Enables dynamic bundle creation based on buyer selections
  • Supports mix-and-match functionality without predefined variants
  • Allows buyers to customize quantities and variants within a bundle
  • More flexible for complex bundle configurations
Cons
  • Buyers cannot pick and choose the quantities or variants unless those combinations are pre-defined
  • Requires creating and managing metafield definitions
  • Each bundle variation needs to be predefined as a separate product variant
  • Line item properties can be modified by the browser, so they should not be relied upon for security or validation purposes
  • Requires additional validation logic in your cart transform function
  • May need extra UI components to manage bundle selections

Anchor to Limitations and considerationsLimitations and considerations

  • A bundle can have up to 150 components.
  • After an app has assigned components to a bundle, only that app can manage the components of the bundle.
  • Nested bundles aren't supported. A bundle can't have components and be part of another bundle simultaneously.

Anchor to Step 1: Generate a new extensionStep 1: Generate a new extension

To create a cart transform extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

  1. Navigate to your app directory:

    Terminal

    cd <directory>

  2. Run the following command to create the app extension:

    Terminal

    shopify app generate extension --template cart_transform --name demo-cart-transform-extension

  1. Choose the language that you want to use. For this tutorial, you should select either Rust or JavaScript.

    Shopify defaults to Rust as the most performant and recommended language choice to stay within the platform limits. For more information, refer to language considerations.

    Terminal

    ? What would you like to work in?
    > (1) Rust
    (2) JavaScript
    (3) TypeScript
    (4) Wasm

  1. Navigate to extensions/demo-cart-transform-extension:

    Terminal

    cd extensions/demo-cart-transform-extension

Anchor to Step 2: Define the input of your functionStep 2: Define the input of your function

run.graphql defines the input for the function target. The following example shows an input that retrieves information about buyer's cart like merchandise, quantity etc.

Replace the contents of src/run.graphql file with the following code.

Customized bundle example

src/run.graphql

query Input {
cart {
lines {
id
quantity
merchandise {
__typename
... on ProductVariant {
id
component_reference: metafield(
namespace: "custom"
key: "component_reference"
) {
jsonValue
}
}
}
}
}
}

Resolved input

{
"cart": {
"lines": [
{
"id": "gid://shopify/CartLine/1",
"quantity": 1,
"merchandise": {
"__typename": "ProductVariant",
"id": "gid://shopify/ProductVariant/1099",
"title": "Something not bundled"
}
},
{
"id": "gid://shopify/CartLine/4",
"quantity": 9,
"merchandise": {
"__typename": "ProductVariant",
"id": "gid://shopify/ProductVariant/1111",
"title": "A neat bundle",
"component_reference": {
"jsonValue": ["gid://shopify/ProductVariant/111","gid://shopify/ProductVariant/222"]
}
}
}
]
}
}

The Function API references provide information on the available fields for the input query.

Note

CartTransform only supports a subset of cart fields. For the list of supported cart fields, refer to the cart input field.

Anchor to Step 3: Define the business logic of your functionStep 3: Define the business logic of your function

In this example, our function will output expand operations for cart lines where merchandise has a metafield referencing other bundle components.

Replace the contents of src/main.rs file with the following code.

main.rs

use shopify_function::prelude::*;
use std::process;

pub mod run;

#[typegen("schema.graphql")]
pub mod schema {
#[query("src/run.graphql", custom_scalar_overrides = {
"Input.cart.lines.merchandise.component_reference.jsonValue" => super::run::ComponentReferences,
})]
pub mod run {}
}

fn main() {
eprintln!("Please invoke a named export.");
process::exit(1);
}

Replace the contents of src/run.rs file with the following code.

run.rs

use super::schema;
use std::borrow::Cow;

use shopify_function::prelude::*;
use shopify_function::Result;

#[shopify_function]
fn run(input: schema::run::Input) -> Result<schema::CartTransformRunResult> {
let cart_operations: Vec<schema::Operation> = get_expand_cart_operations(&input.cart());

Ok(schema::CartTransformRunResult {
operations: cart_operations,
})
}

// expand operation logic

fn get_expand_cart_operations(cart: &schema::run::input::Cart) -> Vec<schema::Operation> {
let mut result: Vec<schema::Operation> = Vec::new();

for line in cart.lines().iter() {
let variant = match &line.merchandise() {
schema::run::input::cart::lines::Merchandise::ProductVariant(variant) => Some(variant),
_ => None,
};
if variant.is_none() {
continue;
}

if let Some(merchandise) = &variant {
let component_references = get_component_references(&merchandise);

if component_references.is_empty() {
continue;
}

let mut expand_relationships: Vec<schema::ExpandedItem> = Vec::new();

for reference in component_references.iter() {
let expand_relationship = schema::ExpandedItem {
merchandise_id: reference.clone(),
quantity: 1,
price: None,
attributes: None,
};

expand_relationships.push(expand_relationship);
}

let expand_operation = schema::LineExpandOperation {
cart_line_id: line.id().clone(),
expanded_cart_items: expand_relationships,
price: None,
image: None,
title: None,
};

result.push(schema::CartOperation::Expand(expand_operation));
}
}

return result;
}

pub type ComponentReferences = Vec<schema::Id>;

fn get_component_references(
variant: &schema::run::input::cart::lines::merchandise::ProductVariant,
) -> Cow<[schema::Id]> {
if let Some(component_reference_metafield) = &variant.component_reference() {
return component_reference_metafield.json_value().into();
}

return Vec::new().into();
}
Tip

Explore more examples in the function-examples repository.

Anchor to Step 4: Update your app access scopesStep 4: Update your app access scopes

You need to request the write_cart_transforms and write_products access scopes to run the mutations in this guide.

  1. In shopify.app.toml in the root of your app, add the write_cart_transforms scope.

    shopify.app.toml

    # This file stores configurations for your Shopify app.

    scopes = "write_cart_transforms,write_products"

  2. Deploy your updated configuration to Shopify:

    Terminal

    shopify app deploy

  3. Restart your app.

    Terminal

    shopify app dev

  4. Use the URL provided by the CLI to open and re-install your app. You should be prompted to accept the new access scope permissions in your store.

Anchor to Step 5: Create the cartTransform objectStep 5: Create the cartTransform object

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

Note

You can use curl to make following GraphQL requests. Only use the access token of the app for which you are building this extension.

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

    find-function-query.graphql

    query {
    shopifyFunctions(first: 25) {
    nodes {
    app {
    title
    }
    apiType
    title
    id
    }
    }
    }

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

    find-function-result.json

    {
    "app": {
    "title": "your-app-name-here"
    },
    "apiType": "cart_transform",
    "title": "your-cart-transform-name",
    "id": "YOUR_FUNCTION_ID_HERE"
    }

  1. Run the following mutation. Replace YOUR_FUNCTION_ID_HERE with the ID of your function:

    mutation.graphql

    mutation {
    cartTransformCreate(functionId: "YOUR_FUNCTION_ID_HERE") {
    cartTransform {
    id
    functionId
    }
    userErrors {
    field
    message
    }
    }
    }

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

    Tip

    If the mutation returns a Could not find Function error, then confirm that the function ID is correct, that you've installed the app on your development store, and that your app has the write_cart_transforms access scope.

Anchor to Step 6: Create metafield definition to store bundle componentsStep 6: Create metafield definition to store bundle components

mutation.graphql

mutation definitionCreate($definition: MetafieldDefinitionInput!) {
metafieldDefinitionCreate(definition: $definition){
createdDefinition {
id
}
}
}

Variables

{
"definition": {
"key": "component_reference",
"type": "list.variant_reference",
"namespace": "custom",
"name": "bundle component reference",
"ownerType": "PRODUCTVARIANT"
}
}

Anchor to Step 7: Create bundle products along with the componentsStep 7: Create bundle products along with the components

In this tutorial, we will take the example of a meal bundle which contains a burger and fries.

Note

You can use curl to make following GraphQL requests. Only use access token of the app for which you are building this extension.

  1. Create bundle component products, i.e. burger and fries.

    mutation.graphql

    mutation($productInput: ProductInput!) {
    productCreate(input: $productInput) {
    product {
    variants(first: 1) {
    edges {
    node {
    id
    }
    }
    }
    }
    }
    }

    Variables

    {
    "productInput": {
    "status": "ACTIVE",
    "published": true,
    "title": "Burger"
    }
    }

    mutation.graphql

    mutation($productInput: ProductInput!) {
    productCreate(input: $productInput) {
    product {
    variants(first: 1) {
    edges {
    node {
    id
    }
    }
    }
    }
    }
    }

    Variables

    {
    "productInput": {
    "status": "ACTIVE",
    "published": true,
    "title": "Fries"
    }
    }

  2. Create a bundle parent product, i.e. Meal Bundle. This example sets requires_components on the variant of the bundle to true. This is required when the variants is meant to be sold as a bundle only. It prevents the variant from being sold as a regular product in case the function doesn't output an operation. For example, the variant Meal Bundle should always be sold as a bundle with components and not as a regular product.

    mutation.graphql

    mutation($productInput: ProductInput!) {
    productCreate(input: $productInput) {
    product {
    variants(first: 1) {
    edges {
    node {
    id
    }
    }
    }
    }
    }
    }

    Variables

    {
    "productInput": {
    "status": "ACTIVE",
    "published": true,
    "title": "Meal Bundle",
    "variants": [
    {
    "requiresComponents": true,
    "metafields": [
    {
    "namespace": "custom",
    "key": "component_reference",
    "type": "list.variant_reference",
    "value": "[\"gid://shopify/ProductVariant/BURGER_VARIANT_ID\", \"gid://shopify/ProductVariant/FRIES_VARIANT_ID\"]"
    }
    ]
    }
    ],
    "claimOwnership": {
    "bundles": true
    }
    }
    }
Note

We are claiming the ownership of the bundle parent product here. This is required if you need to render the product configuration extension in admin.

Anchor to Step 8: Install the extension on a development storeStep 8: Install the extension on a development store

Note

You can skip this step if you have already reinstalled the app on your store in step 4.

To test your function, you need to make it available to your development store.

  1. If you're developing a function in a language other than JavaScript or TypeScript, ensure you have configured build.watch in your function extension configuration.

  1. Navigate back to your app root:

    Terminal

    cd ../..

  1. Use the Shopify CLI dev command to start app preview:

    Terminal

    shopify app dev

    You can keep the preview running as you work on your function. When you make changes to a watched file, Shopify CLI rebuilds your function and updates the function extension's drafts, so you can immediately test your changes.

  2. Follow the CLI prompts to preview your app, and install it on your development store.

Anchor to Step 9: Preview the functionStep 9: Preview the function

Follow the steps below to test your function on your development store.

  1. Navigate to your online storefront.
  2. Add the meal bundle product to your cart.
  3. Navigate to checkout.
  4. You will now see that your meal bundle product is converted into a bundle which includes a burger and fries.
An image showing a checkout including customized bundle.

Anchor to Step 10: Deploy the extensionStep 10: Deploy the extension

When you're ready to release your changes to users, you can create and release an app version. An app version is a snapshot of your app configuration and all extensions.

  1. Navigate to your app directory.

  2. Run the following command.

    Optionally, you can provide a name or message for the version using the --version and --message flags.

    Terminal

    shopify app deploy

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the deploy command with a --no-release flag. You can release the unreleased app version using Shopify CLI's release command, or through the Partner Dashboard.

Anchor to Next stepsNext steps

Was this page helpful?