# Bundles: Developer Documentation Last updated: May 14, 2025 {% hint style="warning" %} For information on how to set up Bundles within the Smartrr app, view: ๐Ÿงบ [What are Bundles?](/docs/support/admin-portal/bundles.md)\ \ If you're on our ๐Ÿ’Ž Excel plan, our implementation team can set up bundles on your storefront for you. The below provides supporting technical documentation that can be used by in-house developers. {% endhint %} The ability to trigger the bundle-builder modal can be placed anywhere on your site. For example, it can live on a parent bundle PDP as a CTA button: "**Build my bundle**". ### Initial Setup Once Subscription Programs and Bundles have been created in the Smartrr admin, *(see above article link)*, you can add the Smartrr bundle builder button to your shop by taking the following steps: 1. In Smartrr's admin, navigate to Subscription Programs > **Bundles** 2. Click **Manage** 3. **Save** the bundle to the theme (or a duplicate theme) that you want the bundle builder button to appear on

Saving to a theme will inject a snippet into the theme's liquid code.

{% hint style="info" %} Tip: We recommend testing the bundle on a clean [Dawn theme](https://themes.shopify.com/themes/dawn/styles/default) for your shop. This will allow you to preview information about the bundle builder and make it easier to compare end results with your desired custom bundle. ![](/files/UihQiwD1TGYvxnihNYTm) {% endhint %} ### Liquid Customizations & Custom Bundles In the Shopify theme that the bundle has been saved to, click the **"more options" icon** left of the Customize button, click **Edit code** and search for snippets that begin with `smartrr-bundle-`.
In the example above, we've created the bundle **All In Cheese and Fruit Bundle** in Smartrr. The corresponding file `smartrr-bundle-all-in-cheese-and-fruit-bundle.liquid` has been injected into the theme's code. This file contains information about the bundle's name and slug, both of which need to be sent to the cart. {% hint style="info" %} **Tip:** To manually render on any existing page, add `{% render 'smartrr-bundle-``{bundle-name}``' %}` to that page's liquid template. Next, add the following code at the end of \ in theme.liquid: 
  <!-- END SMARTRR RENDER SNIPPET -->
  {% render 'smartrr-bundle-modal', smartrr_default_page_url: '/pages/smartrr-bundle' %}
  {% render 'smartrr-bundle-css' %}
  <!-- BEGIN SMARTRR RENDER SNIPPET -->
\ Be sure to change the page URL (ex.`/pages/bundle`) to the page where you have rendered the bundle. \ \ Prior to that you need to create a liquid file and a page in the Online Store. \ First head to the 'Edit Code' for the theme you are using. In the 'Templates' section create a new liquid file, using 'Page' as a template and '.liquid' as a file extension. Add the code described in the 'Tip' section to that page. \ Head to the Shopify admin, click on the 'Online store' navigation button, then click on 'Pages'. Create a new page and use the 'page.{bundle-name}.liquid' file as a 'Theme template'. Finally, add in the CTA button code that will trigger the bundle to open with the code: ```
Build Your Box
``` {% endhint %}

When smartrr-bundle-{bundle-name}.liquid is rendered on the page, you will see the default bundle builder UI.

Add a test bundle to your cart in your theme. View `/cart.json` after adding to view the line item properties that have been added. {% hint style="info" %} **Tip:** The recommended function for adding to cart is: `addBundleToCartAndRedirect` in `smartrr-bundle-js.liquid`. {% endhint %}
#### Line Item Properties Below are the line item properties that will be added to a given bundle product: ```json { "properties": { "Bundle": "Name of Bundle", "Product1": 4, "Product2": 2, "ProductN": "Number: Quantity", "_smartrr_info": "JSON String: Information about the Bundle" } } ``` Below are the line item properties from the example above, **All In Cheese and Fruit Bundle**. {% code overflow="wrap" %} ```json { "properties": { "Bundle": "All In Cheese And Fruit Bundle", "Brie's Fine Cheese": 1, "Ben's Cheese": 1, "Juicy Apricots": 1, "Red Grapes": 1, "_smartrr_info": "{\"items\":[{\"id\":41346996043967,\"quantity\":1,\"selling_plan\":\"2153971903\"},{\"id\":41300866465983,\"quantity\":1,\"selling_plan\":\"2153971903\"},{\"id\":41925668634815,\"quantity\":1,\"selling_plan\":\"2153971903\"},{\"id\":41925668470975,\"quantity\":1,\"selling_plan\":\"2153971903\"}],\"date\":1670278109299,\"page\":\"https://briescheese.myshopify.com/\",\"bundle\":{\"name\":\"All In Cheese And Fruit Bundle\",\"slug\":\"all-in-cheese-and-fruit-bundle/777cdce8-451d-41d8-9fe4-136c969fa7c0\"}}" } } ``` {% endcode %} {% hint style="info" %} **Note:** `_smartrr_info` is stringified JSON. If you're using a JS object to store these line item properties then be sure to use JSON.stringify when adding this information to cart item properties. {% endhint %} When the JSON is parsed, you'll see: ```json { "items":[ { "id":41346996043967, "quantity":1, "selling_plan":"2153971903" }{ "id":41300866465983, "quantity":1, "selling_plan":"2153971903" }{ "id":41925668634815, "quantity":1, "selling_plan":"2153971903" }{ "id":41925668470975, "quantity":1, "selling_plan":"2153971903" } ], "date":1670278109299, "page":"https://briescheese.myshopify.com", "bundle":{ "name":"All In Cheese And Fruit Bundle", "slug":"all-in-cheese-and-fruit-bundle/777cdce8-451d-41d8-9fe4-136c969fa7c0" } } ``` If a bundle purchase is one-time and not a subscription, `"selling_plan"` will be omitted. Example: ```json { "items":[ { "id":41346996043967, "quantity":1 }{ "id":41300866465983, "quantity":1 }{ "id":41925668634815, "quantity":1 }{ "id":41925668470975, "quantity":1 } ], "date":1670278109299, "page":"https://briescheese.myshopify.com", "bundle":{ "name":"All In Cheese And Fruit Bundle", "slug":"all-in-cheese-and-fruit-bundle/777cdce8-451d-41d8-9fe4-136c969fa7c0" } } ``` Below is a plain-text schema of the parsed JSON: ```json { "Array:items":[ { "id":"Number: Variant Id", "quantity":"Number: Quantity", "selling_plan":"String/Number: Selling Plan ID" } ], "date":"Number: Time of purchase", "page":"URLString: Page of purchase", "Object:bundle":{ "name":"String: Name of Bundle", "slug":"String: Unique Slug of Bundle" } } ``` Below is the JSON schema that can be used for reference: ```json { "$schema":"http://json-schema.org/draft-04/schema#", "type":"object", "properties":{ "items":{ "type":"array", "items":[ { "type":"object", "properties":{ "id":{ "type":"integer" }, "quantity":{ "type":"integer" }, "selling_plan":{ "type":"integer" } }, "required":[ "id", "quantity", "selling_plan" ] } ] }, "date":{ "type":"integer" }, "page":{ "type":"string" }, "bundle":{ "type":"object", "properties":{ "name":{ "type":"string" }, "slug":{ "type":"string" } }, "required":[ "name", "slug" ] } }, "required":[ "items", "date", "page", "bundle" ] } ``` Use these line item properties to integrate with any existing 3PL setup to ensure your bundle contains the correct products. Below is the code for generating line properties( see function `addBundleToCartAndRedirect` in `smartrr-bundle-js.liquid`) ```javascript var bundleInfo = { items: [], date: new Date().getTime(), page: window.location.toString(), bundle: { name: bundle.name, slug: bundle.slug, }, }; ...; /* For each item in bundle */ bundleInfo.items.push({ id: lineItem.variant.id, quantity: lineItem.quantity, selling_plan: sellingPlan, }); properties[lineItem.product.title] = lineItem.quantity; /* End For Each */ ...; properties["Bundle"] = bundle.name; properties["_smartrr_info"] = JSON.stringify(bundleInfo); ``` [^1]: Change this text to be your desired url --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://help.smartrr.com/docs/support/developer-documentation/bundles-developer-documentation.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.