Adding dynamic build-a-box items to the cart

Some merchants prefer to create their own custom checkout flow for their dynamic build-a-box products instead of using the user interface provided by Awtomic. This allows them to add their own unique user experience and features. However, in order for Awtomic to recognize these custom build-a-box products and allow customers to manage their box items in the Awtomic customer portal, specific line item properties must be included on each line of the product.

This article is intended to help theme developers understand which line item properties are required for dynamic build-a-box products when using a custom checkout flow.

🚧

This article is specific to Awtomic's dynamic build-a-box and not the classic version. To learn how to do this for classic build-a-box, use the help article on classic boxes.

Each item in the box should have an ID and a quantity (as any other item added to the cart would), as well as a set of properties that describe details about the bundle it belongs to. These properties include:

• _bundleUid: A unique identifier for the bundle that each item belongs to. If you have multiple bundles in the cart, each bundle will have a different _bundleUid.
• _bundleHandle: The handle of the faux bundle product. This should match the handle of the product that represents the bundle.
• _bundleType: This should be hardcoded to "dynamicBaB" (case sensitive).
• _bundleLabel: The label of the variant, which should match the product variant title (usually something like "X items").
• _bundleProductId: The ID of the faux bundle product (this id needs to be in the admin_graphql_api_id format)
• _bundleName: The name of the faux bundle product, which should match the product title.
• _bundleBoxSize: The number of items in the box (only needed for set box sizes).
• _bundleBoxMinSize: The minimum number of items in the box (only needed for boxes with a minimum).
• _bundleBoxMaxSize: The maximum number of items in the box (only needed for boxes with a maximum).
• _variantId: The selected product variant ID (this id needs to be in the admin_graphql_api_id format)

If you want to add an item to the cart as part of a subscription, you also need to include a selling_plan ID for the item. This ID is located in the selling_plan_allocations, which is part of the variant.

Here's an example of what the items might look like in the body of a POST request to the Cart AJAX API:

items: [ { "id": "12341234", "quantity": 1, "properties": { "_bundleUid": "fcf4854d-8a31-4a54-a267-eb559cab5aac", "_bundleHandle": "build-your-own-box", "_bundleType": "dynamicBaB", "_bundleLabel": "6 items", "_bundleProductId": "gid://shopify/Product/6952538996872", "_bundleName": "Build Your Own Box", "_bundleBoxSize": 6, "_variantId": "gid://shopify/ProductVariant/40491125899400" }, "selling_plan": "12345678" }, // additional items in the cart...]

In this example, we're adding an item to the cart with an ID of "12341234" and a quantity of 1. The properties for the bundle include the unique bundle UID, the handle and type of the faux bundle product, the label and product ID of the variant, the name and size of the faux bundle product, and the ID of the selected product variant.

We're also including a selling plan ID of "12345678" for this item, indicating that it should be added to the cart as part of a subscription.

---

A good way to see if you're adding the correct properties to the items is to use Awtomic's built-in box checkout flow and view the properties that are put on items in the cart. To pull the items in a Shopify cart using the Cart AJAX API, you can send a GET request to the /cart.js endpoint. This will return a JSON object containing information about the items in the cart, including their product ID, variant ID, quantity, price, and other properties.

Here's an example of how you might use the Cart AJAX API to retrieve the items in the cart:

fetch('/cart.js') .then(response => response.json()) .then(cart => { // do something with the cart data console.log(cart.items); }) .catch(error => { console.log('Error getting cart data: ' + error); });