Build-a-Box & Bundles
Retrieve a Build-A-Box bundle by ID
Fetches the complete configuration and details of a specific Build-A-Box subscription bundle using its unique identifier. This endpoint returns all bundle settings including products, pricing, rules, and delivery options.
What You’ll Receive:
- Complete Bundle Configuration: All settings and properties
- Product Information: Full list of available products with details
- Pricing Structure: Discount rules, pricing type, and promotional settings
- Delivery Options: Subscription frequencies and delivery intervals
- Business Rules: Product limits, combination rules, and restrictions
- Status Information: Active/inactive state and timestamps
- Customization Settings: Allow one-time purchases, product swaps, etc.
Use Cases:
- Bundle Management: Retrieve current bundle settings for review or editing
- Integration Sync: Synchronize bundle data with external systems
- Customer Portal: Display bundle options and configurations
- Audit & Reporting: Track bundle configurations over time
- Validation: Verify bundle setup before making changes
- Cloning: Retrieve settings to duplicate a successful bundle
- Troubleshooting: Debug subscription issues by reviewing bundle config
Response Details: The response includes comprehensive information about the bundle:
- Bundle Metadata: ID, shop, name, handle, unique reference
- Product Pool: All products available for customer selection
- Selection Rules: Min/max product counts, quantity limits
- Pricing Configuration: Discount percentages, pricing models
- Subscription Options: Available delivery frequencies
- Display Settings: Product view styles, custom HTML, button text
- Advanced Features: Third-party rules, inventory tracking, selection types
- Timestamps: Creation and last update dates
Authorization:
- You can only retrieve bundles that belong to your authenticated shop
- The system verifies shop ownership before returning bundle data
- Returns 404 if bundle doesn’t exist or doesn’t belong to your shop
Integration Tips:
- Cache bundle data to reduce API calls for frequently accessed bundles
- Use this endpoint to verify bundle existence before creating subscriptions
- Combine with update endpoint for edit workflows (get → modify → update)
- Check the
activefield to determine if the bundle is available to customers - Review
availableProductsarray to ensure product inventory availability
Performance Considerations:
- Response size varies based on number of products in the bundle
- Bundles with extensive custom HTML or large product pools return more data
- Consider requesting only necessary fields if partial data is sufficient
- Use batch operations if retrieving multiple bundles
Authentication: Requires valid X-API-Key header or api_key parameter (deprecated)
GET
/
api
/
external
/
v2
/
build-a-box
/
{id}
Retrieve a Build-A-Box bundle by ID
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}', 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/{id}';
const options = {method: 'GET'};
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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}"
req, _ := http.NewRequest("GET", url, nil)
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/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"active": true,
"allowOneTimePurchase": true,
"availableProducts": [
{
"available": true,
"imageUrl": "https://cdn.shopify.com/coffee-medium.jpg",
"price": "14.99",
"productId": 111111,
"title": "Medium Roast Coffee - 12oz",
"variantId": 222222
},
{
"available": true,
"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",
"chooseProductsText": "Build Your Perfect Coffee Box",
"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,
"minOrderAmount": 25,
"minProductCount": 2,
"pricingType": "PER_PRODUCT",
"proceedToCheckoutButtonText": "Complete Your Subscription",
"productViewStyle": "GRID",
"shop": "example-shop.myshopify.com",
"thirdPartyRule": false,
"trackInventory": true,
"uniqueRef": "bab_abc123xyz",
"updatedAt": "2024-03-20T14:45:00Z"
}{
"detail": "Valid X-API-Key header or api_key parameter is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "No Build-A-Box bundle found with ID 45678 for your shop",
"status": 404,
"title": "Bundle not found",
"type": "https://example.com/errors/not-found"
}{
"detail": "An unexpected error occurred while retrieving the Build-A-Box bundle",
"status": 500,
"title": "Internal server error",
"type": "https://example.com/errors/internal-server-error"
}Headers
Path Parameters
Query Parameters
API Key (Deprecated - Use Header X-API-Key instead)
Response
Build-A-Box bundle successfully retrieved
Available options:
PRODUCT, COLLECTION, BOTH, ONE_TIME, SUBSCRIPTION 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 Available options:
CART, CART_DRAWER, CHECKOUT, CUSTOM, NONE Available options:
ADD_CHILD_PRODUCT_ON_ORDER, ADD_CHILD_PRODUCT_ON_CHECKOUT Available options:
SELECTED_PRODUCT, EACH_PRODUCT Available options:
PRODUCT, COLLECTION Available options:
QUICK_ADD, VIEW_DETAILS Available options:
FIXED, FLEXIBLE ⌘I
Retrieve a Build-A-Box bundle by ID
curl --request GET \
--url https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}import requests
url = "https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}"
response = requests.get(url)
print(response.text)const options = {method: 'GET'};
fetch('https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}', 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/{id}';
const options = {method: 'GET'};
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/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://subscription-admin.appstle.com/api/external/v2/build-a-box/{id}"
req, _ := http.NewRequest("GET", url, nil)
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/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
response = http.request(request)
puts response.read_body{
"active": true,
"allowOneTimePurchase": true,
"availableProducts": [
{
"available": true,
"imageUrl": "https://cdn.shopify.com/coffee-medium.jpg",
"price": "14.99",
"productId": 111111,
"title": "Medium Roast Coffee - 12oz",
"variantId": 222222
},
{
"available": true,
"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",
"chooseProductsText": "Build Your Perfect Coffee Box",
"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,
"minOrderAmount": 25,
"minProductCount": 2,
"pricingType": "PER_PRODUCT",
"proceedToCheckoutButtonText": "Complete Your Subscription",
"productViewStyle": "GRID",
"shop": "example-shop.myshopify.com",
"thirdPartyRule": false,
"trackInventory": true,
"uniqueRef": "bab_abc123xyz",
"updatedAt": "2024-03-20T14:45:00Z"
}{
"detail": "Valid X-API-Key header or api_key parameter is required",
"status": 401,
"title": "Authentication required",
"type": "https://example.com/errors/unauthorized"
}{
"detail": "No Build-A-Box bundle found with ID 45678 for your shop",
"status": 404,
"title": "Bundle not found",
"type": "https://example.com/errors/not-found"
}{
"detail": "An unexpected error occurred while retrieving the Build-A-Box bundle",
"status": 500,
"title": "Internal server error",
"type": "https://example.com/errors/internal-server-error"
}