Adding a classic build-a-box to the cart

Some merchants prefer to create their own custom checkout flow for their classic 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 the box product when it's added to the cart.

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

🚧

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

When you add a classic build-a-box to the cart, its represented by a single line in the cart with properties that describe details about the bundle as well as and each item selected by the customer. These properties include:

• _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.
• _bundleName: The name of the faux bundle product, which should match the product title.
• _bundleBoxSize: The number of items in the box.
• _bundleBoxPrice: The cost of this box size.
• _variantId: The product variant ID of the selected variant of the faux bundle (this id needs to be in the admin_graphql_api_id format)

For each item or selection in the box, you should also include the following properties:

• _pv_{productVariantId}: The key should be the product variant ID (just the numeric id) of the selected item, prefixed with pv, and the value should be the selected quantity of that variant.
• {Product Variant Name}: The key should be the product variant name of the selected item, and the value should be the selected quantity of that variant.

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:

[
  { 
    "id": "12341234",
    "quantity": 1, 
    "properties": { 
      "_bundleLabel": "6 items",
      "_bundleProductId": "gid://shopify/Product/6952538996872",
      "_bundleName": "Build Your Own Box",
      "_bundleBoxSize": 6, 
      "_bundleBoxPrice": 60, 
      "_variantId": "gid://shopify/ProductVariant/40491125899400",
      "_pv_87654321": 3, 
      "_pv_34567890": 3, 
      "Strawberry Banana": 3, 
      "Chocolate Crunch": 3 
    }, 
    "selling_plan": "12345678" 
  }, 
  // additional items in the cart...
]

In this example, we're adding the box product item to the cart with an ID of "12341234" and a quantity of 1. The properties for the bundle include the name, label and product ID of the build-a-box product, the size and price of the box, and the ID of the selected box variant. We're also including properties for each selection in the box, using the product variant ID and name as the keys and the selected quantity as the value.

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);
  });