Build-a-Box & Bundles

Update an existing Build-A-Box subscription bundle

Updates an existing Build-A-Box subscription bundle with new configuration settings, product selections, pricing rules, or other bundle attributes. This endpoint allows you to modify any aspect of a previously created bundle while maintaining its unique identifier and shop association.

What Can Be Updated:

Bundle Information: Name, description, handle, and display settings
Product Configuration: Available products, product pool, and selection rules
Quantity Limits: Minimum and maximum product counts per box
Pricing Settings: Pricing type, discount rules, and promotional offers
Delivery Options: Subscription frequencies and delivery intervals
Business Rules: Product combination rules, category restrictions
Status: Active/inactive state for customer visibility
Customization Options: Allow product swaps, one-time purchases

Update Behavior:

The bundle ID must be provided in the request body
Shop ownership is verified - you can only update bundles belonging to your shop
All fields in the request body will update the corresponding bundle properties
Partial updates are supported - only include fields you want to change
The update is atomic - either all changes succeed or none are applied
Existing subscriptions using this bundle are not automatically affected

Impact on Active Subscriptions:

Changes to product availability affect future customer selections
Pricing updates apply to new subscriptions but not existing ones by default
Quantity limit changes are enforced on next customer modification
Frequency changes only affect new subscriptions
Deactivating a bundle prevents new subscriptions but maintains existing ones

Common Update Scenarios:

Add/Remove Products: Update the available product pool
Adjust Pricing: Change discount percentages or pricing models
Modify Limits: Update minimum/maximum product selection rules
Change Frequencies: Add or remove subscription interval options
Update Content: Modify bundle name, description, or images
Toggle Status: Activate or deactivate bundle availability
Refine Rules: Adjust product combination or category restrictions

Best Practices:

Verify product availability before adding to the bundle
Test pricing changes with sample calculations
Communicate bundle changes to existing subscribers
Use inactive status for testing changes before making them live
Keep bundle handles consistent for external integrations
Document major changes for customer support reference
Consider seasonal or promotional updates to keep offerings fresh

Validation Rules:

Bundle ID is required and must exist
Shop must match the authenticated shop (cannot transfer bundles)
All referenced products must be valid and available
Minimum product count cannot exceed maximum product count
Pricing values must be non-negative
Bundle handle should remain unique across all bundles

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

PUT

api

external

build-a-box

Update an existing Build-A-Box subscription bundle

curl --request PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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: 'PUT',
  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 => "PUT",
  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("PUT", 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::Put.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": [
    {
      "price": "14.99",
      "productId": 111111,
      "title": "Medium Roast Coffee - 12oz",
      "variantId": 222222
    },
    {
      "price": "15.99",
      "productId": 111111,
      "title": "Dark Roast Coffee - 12oz",
      "variantId": 333333
    },
    {
      "price": "16.99",
      "productId": 111111,
      "title": "Espresso Roast Coffee - 12oz",
      "variantId": 444444
    }
  ],
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "bundleHandle": "premium-coffee-selection",
  "bundleName": "Premium Coffee Selection - Updated",
  "createdAt": "2024-03-15T10:30:00Z",
  "description": "Choose from our expanded selection of artisan coffee blends",
  "discount": 15,
  "discountType": "PERCENTAGE",
  "frequencies": [
    {
      "displayName": "Monthly",
      "interval": "MONTH",
      "intervalCount": 1
    },
    {
      "displayName": "Bi-Weekly",
      "interval": "WEEK",
      "intervalCount": 2
    }
  ],
  "id": 45678,
  "maxProductCount": 6,
  "minProductCount": 3,
  "pricingType": "PER_PRODUCT",
  "shop": "example-shop.myshopify.com",
  "uniqueRef": "bab_abc123xyz",
  "updatedAt": "2024-03-20T14:45: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,

CHECKOUT,

CUSTOM,

NONE

bundleTopHtml

string

chooseProductsText

string

collectionData

string

customRedirectURL

string

discount

number<double>

discountedVariants

string

groupName

string

integer<int64>

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 updated

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,

CHECKOUT,

CUSTOM,

NONE

bundleTopHtml

string

chooseProductsText

string

collectionData

string

customRedirectURL

string

discount

number<double>

discountedVariants

string

groupName

string

integer<int64>

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

Cancel a subscription contract

Create a new Build-A-Box subscription bundle

Update an existing Build-A-Box subscription bundle

curl --request PUT \
  --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.put(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PUT',
  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: 'PUT',
  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 => "PUT",
  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("PUT", 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::Put.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": [
    {
      "price": "14.99",
      "productId": 111111,
      "title": "Medium Roast Coffee - 12oz",
      "variantId": 222222
    },
    {
      "price": "15.99",
      "productId": 111111,
      "title": "Dark Roast Coffee - 12oz",
      "variantId": 333333
    },
    {
      "price": "16.99",
      "productId": 111111,
      "title": "Espresso Roast Coffee - 12oz",
      "variantId": 444444
    }
  ],
  "buildABoxType": "SINGLE_PRODUCT",
  "buildBoxVersion": "V2",
  "bundleHandle": "premium-coffee-selection",
  "bundleName": "Premium Coffee Selection - Updated",
  "createdAt": "2024-03-15T10:30:00Z",
  "description": "Choose from our expanded selection of artisan coffee blends",
  "discount": 15,
  "discountType": "PERCENTAGE",
  "frequencies": [
    {
      "displayName": "Monthly",
      "interval": "MONTH",
      "intervalCount": 1
    },
    {
      "displayName": "Bi-Weekly",
      "interval": "WEEK",
      "intervalCount": 2
    }
  ],
  "id": 45678,
  "maxProductCount": 6,
  "minProductCount": 3,
  "pricingType": "PER_PRODUCT",
  "shop": "example-shop.myshopify.com",
  "uniqueRef": "bab_abc123xyz",
  "updatedAt": "2024-03-20T14:45:00Z"
}