Build-a-Box & Bundles

Create a new Build-A-Box subscription bundle

Creates a new subscription bundle (Build-A-Box) allowing customers to select and customize products for recurring deliveries. Build-A-Box enables a flexible subscription model where customers can create personalized product boxes.

What is Build-A-Box? Build-A-Box is a subscription feature that allows customers to curate their own product bundles by selecting from a predefined set of products. This creates a highly personalized subscription experience where customers have full control over what they receive in each delivery cycle.

Key Features:

Product Selection: Customers choose which products to include in their box
Quantity Control: Set minimum and maximum product quantities
Flexible Configuration: Define rules for product combinations
Pricing Models: Support for various pricing strategies (per-item, flat rate, tiered)
Recurring Delivery: Automatic fulfillment based on subscription frequency
Customization Options: Allow product swaps between delivery cycles

Configuration Options:

Bundle Settings:
- Bundle name and description
- Unique handle for identification
- Product pool (available products for selection)
- Minimum/maximum number of products
- Product quantity limits
Pricing Configuration:
- Pricing type (per-product, flat rate, or tiered)
- Discount rules
- Promotional pricing
- Currency settings
Delivery Options:
- Subscription frequencies (weekly, bi-weekly, monthly, etc.)
- Delivery intervals
- Cut-off times for order modifications
- Shipping methods
Rules and Restrictions:
- Product combination rules
- Category restrictions
- Inventory requirements
- Customer eligibility criteria

Build-A-Box Types:

Open Selection: Customers can choose any products from the available pool
Category-Based: Products are organized into categories with selection rules
Single Product: Customers select variations of a single product type
Tiered Boxes: Different box sizes with varying product counts and pricing

Use Cases:

Coffee Subscription: Customers select different coffee blends for monthly delivery
Snack Boxes: Build custom snack boxes from a variety of treats
Beauty Boxes: Choose skincare and makeup products based on preferences
Meal Kits: Select recipes and ingredients for weekly meal planning
Pet Supply Boxes: Customize toys, treats, and supplies for pets
Supplement Subscriptions: Create personalized vitamin and supplement regimens

Customer Workflow:

Customer discovers Build-A-Box offering
Selects products from available options
Chooses delivery frequency
Reviews pricing and discounts
Completes subscription signup
Receives recurring deliveries
Can modify selections between delivery cycles

Important Notes:

Each bundle must have a unique handle for identification
Product availability is validated at creation time
Pricing rules are applied based on bundle configuration
Bundles must be associated with at least one subscription frequency
Inventory levels should be checked for all included products
Bundle status (active/inactive) controls customer visibility

Best Practices:

Set clear minimum and maximum product limits
Provide detailed product descriptions and images
Configure appropriate pricing that encourages subscriptions
Offer multiple delivery frequency options
Set reasonable inventory thresholds
Enable customer portal access for subscription management
Test bundle configurations before making them live

Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)

POST

api

external

build-a-box

Create a new Build-A-Box subscription bundle

curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/build-a-box \
  --header 'Content-Type: application/json' \
  --data '
{
  "shop": "<string>"
}
'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/build-a-box"

payload = { "shop": "<string>" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({shop: '<string>'})
};

fetch('https://subscription-admin.appstle.com/api/external/v2/build-a-box', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/build-a-box';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({shop: '<string>'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/build-a-box",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'shop' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/build-a-box"

	payload := strings.NewReader("{\n  \"shop\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/build-a-box")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shop\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "active": true,
  "allowOneTimePurchase": true,
  "availableProducts": [
    {
      "imageUrl": "https://cdn.shopify.com/coffee-medium.jpg",
      "price": "14.99",
      "productId": 111111,
      "title": "Medium Roast Coffee - 12oz",
      "variantId": 222222
    },
    {
      "imageUrl": "https://cdn.shopify.com/coffee-dark.jpg",
      "price": "15.99",
      "productId": 111111,
      "title": "Dark Roast Coffee - 12oz",
      "variantId": 333333
    }
  ],
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "bundleHandle": "premium-coffee-selection",
  "bundleName": "Premium Coffee Selection",
  "createdAt": "2024-03-15T10:30:00Z",
  "description": "Choose your favorite coffee blends for monthly delivery",
  "discount": 10,
  "discountType": "PERCENTAGE",
  "frequencies": [
    {
      "displayName": "Monthly",
      "interval": "MONTH",
      "intervalCount": 1
    },
    {
      "displayName": "Bi-Weekly",
      "interval": "WEEK",
      "intervalCount": 2
    }
  ],
  "id": 45678,
  "maxProductCount": 5,
  "minProductCount": 2,
  "pricingType": "PER_PRODUCT",
  "shop": "example-shop.myshopify.com",
  "uniqueRef": "bab_abc123xyz",
  "updatedAt": "2024-03-15T10:30:00Z"
}

Headers

X-API-Key

string

Query Parameters

api_key

string

API Key (Deprecated - Use Header X-API-Key instead)

Body

application/json

shop

string

required

allowOneTimePurchase

boolean

appliesOn

enum<string>

Available options:

PRODUCT,

COLLECTION,

BOTH,

ONE_TIME,

SUBSCRIPTION

buildABoxType

enum<string>

Available options:

CLASSIC,

SINGLE_PRODUCT,

MIX_AND_MATCH,

INFINITE,

CUSTOMIZE_BUNDLE,

CLASSIC_BUILD_A_BOX,

SINGLE_PRODUCT_BUILD_A_BOX,

VOLUME_DISCOUNT,

DISCOUNTED_PRICING,

SHIPPING_DISCOUNT,

BUY_X_GET_Y,

SECTIONED_BUNDLE

bundleBottomHtml

string

bundleRedirect

enum<string>

Available options:

CART,

CART_DRAWER,

CHECKOUT,

CUSTOM,

NONE

bundleTopHtml

string

chooseProductsText

string

collectionData

string

customRedirectURL

string

discount

number<double>

discountedVariants

string

groupName

string

integer<int64>

inventoryTrackingMode

enum<string>

Available options:

ADD_CHILD_PRODUCT_ON_ORDER,

ADD_CHILD_PRODUCT_ON_CHECKOUT

maxProductCount

integer<int32>

minOrderAmount

number<double>

minProductCount

integer<int32>

minUniqueProductCheck

boolean

name

string

proceedToCheckoutButtonText

string

productDiscountType

enum<string>

Available options:

SELECTED_PRODUCT,

EACH_PRODUCT

productSelectionType

enum<string>

Available options:

PRODUCT,

COLLECTION

productViewStyle

enum<string>

Available options:

QUICK_ADD,

VIEW_DETAILS

sections

string

selectionType

enum<string>

Available options:

FIXED,

FLEXIBLE

sellingPlanIds

string

singleProductSettings

string

subscriptionBundleLink

string

subscriptionBundlingEnabled

boolean

subscriptionGroup

string

subscriptionId

integer<int64>

thirdPartyRule

boolean

tieredDiscount

string

trackInventory

boolean

uniqueRef

string

variants

string

Response

Build-A-Box subscription bundle successfully created

shop

string

required

allowOneTimePurchase

boolean

appliesOn

enum<string>

Available options:

PRODUCT,

COLLECTION,

BOTH,

ONE_TIME,

SUBSCRIPTION

buildABoxType

enum<string>

Available options:

CLASSIC,

SINGLE_PRODUCT,

MIX_AND_MATCH,

INFINITE,

CUSTOMIZE_BUNDLE,

CLASSIC_BUILD_A_BOX,

SINGLE_PRODUCT_BUILD_A_BOX,

VOLUME_DISCOUNT,

DISCOUNTED_PRICING,

SHIPPING_DISCOUNT,

BUY_X_GET_Y,

SECTIONED_BUNDLE

bundleBottomHtml

string

bundleRedirect

enum<string>

Available options:

CART,

CART_DRAWER,

CHECKOUT,

CUSTOM,

NONE

bundleTopHtml

string

chooseProductsText

string

collectionData

string

customRedirectURL

string

discount

number<double>

discountedVariants

string

groupName

string

integer<int64>

inventoryTrackingMode

enum<string>

Available options:

ADD_CHILD_PRODUCT_ON_ORDER,

ADD_CHILD_PRODUCT_ON_CHECKOUT

maxProductCount

integer<int32>

minOrderAmount

number<double>

minProductCount

integer<int32>

minUniqueProductCheck

boolean

name

string

proceedToCheckoutButtonText

string

productDiscountType

enum<string>

Available options:

SELECTED_PRODUCT,

EACH_PRODUCT

productSelectionType

enum<string>

Available options:

PRODUCT,

COLLECTION

productViewStyle

enum<string>

Available options:

QUICK_ADD,

VIEW_DETAILS

sections

string

selectionType

enum<string>

Available options:

FIXED,

FLEXIBLE

sellingPlanIds

string

singleProductSettings

string

subscriptionBundleLink

string

subscriptionBundlingEnabled

boolean

subscriptionGroup

string

subscriptionId

integer<int64>

thirdPartyRule

boolean

tieredDiscount

string

trackInventory

boolean

uniqueRef

string

variants

string

Create a new Build-A-Box subscription bundle

curl --request POST \
  --url https://subscription-admin.appstle.com/api/external/v2/build-a-box \
  --header 'Content-Type: application/json' \
  --data '
{
  "shop": "<string>"
}
'

import requests

url = "https://subscription-admin.appstle.com/api/external/v2/build-a-box"

payload = { "shop": "<string>" }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({shop: '<string>'})
};

fetch('https://subscription-admin.appstle.com/api/external/v2/build-a-box', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const url = 'https://subscription-admin.appstle.com/api/external/v2/build-a-box';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({shop: '<string>'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://subscription-admin.appstle.com/api/external/v2/build-a-box",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'shop' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://subscription-admin.appstle.com/api/external/v2/build-a-box"

	payload := strings.NewReader("{\n  \"shop\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://subscription-admin.appstle.com/api/external/v2/build-a-box")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"shop\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "active": true,
  "allowOneTimePurchase": true,
  "availableProducts": [
    {
      "imageUrl": "https://cdn.shopify.com/coffee-medium.jpg",
      "price": "14.99",
      "productId": 111111,
      "title": "Medium Roast Coffee - 12oz",
      "variantId": 222222
    },
    {
      "imageUrl": "https://cdn.shopify.com/coffee-dark.jpg",
      "price": "15.99",
      "productId": 111111,
      "title": "Dark Roast Coffee - 12oz",
      "variantId": 333333
    }
  ],
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "bundleHandle": "premium-coffee-selection",
  "bundleName": "Premium Coffee Selection",
  "createdAt": "2024-03-15T10:30:00Z",
  "description": "Choose your favorite coffee blends for monthly delivery",
  "discount": 10,
  "discountType": "PERCENTAGE",
  "frequencies": [
    {
      "displayName": "Monthly",
      "interval": "MONTH",
      "intervalCount": 1
    },
    {
      "displayName": "Bi-Weekly",
      "interval": "WEEK",
      "intervalCount": 2
    }
  ],
  "id": 45678,
  "maxProductCount": 5,
  "minProductCount": 2,
  "pricingType": "PER_PRODUCT",
  "shop": "example-shop.myshopify.com",
  "uniqueRef": "bab_abc123xyz",
  "updatedAt": "2024-03-15T10:30:00Z"
}

Get Started

Guides

Partner Integration

Webhooks

Admin API

Storefront API

Resources

Create a new Build-A-Box subscription bundle

Headers

Query Parameters

Body

Response