# 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?](https://help.smartrr.com/docs/support/admin-portal/bundles)\
\
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.
{% 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:
\
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
