Building a 'Build-a-Box' Subscription Offer with Skio on Shopify
Build-a-Box is a subscription model where customers curate their own recurring box choosing which products they want included each delivery cycle. For supplement, coffee, and food subscription brands, this dramatically improves subscriber retention because customers feel in control of what they receive.
Skio is a Shopify subscription app that powers subscription programs for brands like Liquid I.V., Graza, and Magic Spoon. Implementing a custom Build-a-Box flow on top of Skio requires understanding how Skio's data model works beneath the Shopify surface. This isn't documented in any single guide you piece it together from Skio's API docs, Shopify's Selling Plan API, and real testing.
How Skio Works Under the Hood
Skio is built on top of Shopify's native Selling Plans API. When you create a subscription plan in Skio, it creates a Selling Plan Group in Shopify and attaches it to products. Each selling plan defines the billing interval (weekly, monthly, etc.) and the discount applied to subscribers.
When a customer subscribes through Skio, Shopify creates a subscription contract, a recurring billing agreement. Skio manages the contract lifecycle (pausing, skipping, swapping products, cancelling) through their interface and API, while Shopify Payments handles the recurring billing.
Why Skio Over Older Apps
Unlike Recharge or Bold (which historically used draft orders and custom checkout flows), Skio uses Shopify's native Selling Plans and standard checkout. Subscribers go through Shopify's own checkout, which converts better and doesn't require managing a separate payment processor or redirect.
Architecting the Build-a-Box UI
The Build-a-Box UI lives on the storefront, typically a custom Liquid page. Customers browse available products, select what they want (e.g., any 3 items), and the page adds all selected variants to the cart with the subscription selling plan applied to each.
The key technical challenge: you need to tell Skio which variants are included in the bundle and in what quantities. Skio does this through a single parent line item whose properties encode the children, each selected variant gets a property keyed as _pv{variantId} (the pvgid) with its quantity as the value. Important: the variantId here must be the Shopify resource ID (the full gid://shopify/ProductVariant/{id} format), not the plain numeric variant ID. Skio uses the resource ID to look up variants in the subscription contract. A human-readable Box property is also set summarising the selections. Skio reads these properties to construct the subscription contract with the correct bundle contents.
async function addBoxToCart(selections, variantData, sellingPlanId) {
// Build the primary line item properties
// Skio identifies bundle children via _pv{variantId} properties (pvgid)
const properties = {};
const bundleDescription = [];
for (const [id, quantity] of Object.entries(selections)) {
if (quantity > 0 && variantData[id]) {
bundleDescription.push(`${variantData[id].title} (x${quantity})`);
const childrenKey = `_pv${id}`;
properties[childrenKey] = quantity;
}
}
properties['Box'] = bundleDescription.join(', ');
const response = await fetch('/cart/add.js', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
items: [{
id: sellingPlanId,
quantity: 1,
selling_plan: sellingPlanId,
properties
}]
})
});
if (!response.ok) throw new Error('Failed to add box to cart');
return response.json();
}Managing the Subscription After Purchase
After subscribing, customers need to swap products in future boxes, that's the whole value of Build-a-Box. Skio provides a customer portal (hosted or embeddable) where subscribers manage their contracts. For fully custom implementations, Skio's API lets you fetch subscription contracts and update line items programmatically.
The most important thing to understand: when a subscriber swaps a product, Skio updates the subscription contract, not the original Shopify order. The next charge will reflect the updated selection. This is a fundamentally different data flow from one-time purchases and requires careful UX to keep customers informed about when changes take effect.
Test Your Full Subscription Flow
Skio provides a test mode with a Shopify development store. Always test the full subscribe → manage → swap → skip → cancel flow before going live. Subscription billing issues are extremely difficult to fix retroactively and cause serious customer trust problems.