If you're building a custom storefront experience for your Build-a-Box bundles instead of using Appstle's built-in widget, you can retrieve your bundle configuration through the Appstle External API.

This API returns everything needed to build your own experience, including:

Bundle information
Product and variant details
Bundle rules (minimum/maximum products)
Discount configuration
Subscription delivery frequencies

Before You Begin

You'll need:

An Appstle External API Key
The Build-a-Box Handle (the unique handle assigned to your bundle)

Step 1: Generate an API Key

Open your Appstle Subscriptions admin.
Navigate to Settings → External APIs.
Click Generate API Key.
Copy the generated key immediately.

Your API key will look similar to:

apst_xxxxxxxxxxxxxxxxxxxxxxxxx

Important

API keys are displayed only once. If you lose the key, you'll need to generate a new one.

Keep your API key secure and never expose it in frontend JavaScript or publicly accessible code. We strongly recommend making API calls from your backend/server.

Step 2: Find Your Build-a-Box Handle

Every Build-a-Box bundle has a unique handle that identifies it.

Example:

premium-coffee-selection

You'll use this handle when requesting the bundle configuration.

Step 3: Retrieve the Bundle

Send a GET request to:

https://<your-app-domain>/api/external/v2/build-a-box/{handle}

Replace:

<your-app-domain> with your Appstle domain
{handle} with your Build-a-Box handle

Required Header

X-API-Key: apst_xxxxxxxxxxxxxxxxxxxxxxxxx

Example Request

curl -X GET \ "https://app.appstle.com/api/external/v2/build-a-box/premium-coffee-selection" \ -H "X-API-Key: apst_xxxxxxxxxxxxxxxxxxxxxxxxx"

Example Response

{
  "bundle": {
"id": 45678,
"bundleName": "Premium Coffee Selection",
"bundleHandle": "premium-coffee-selection",
"description": "Choose your favorite coffee blends for monthly delivery",
"minProductCount": 2,
"maxProductCount": 5,
"discount": 10,
"discountType": "PERCENTAGE",
"allowOneTimePurchase": true,
"active": true,
"products": [
{
"productId": 111111,
"variantId": 222222,
"title": "Medium Roast Coffee - 12oz",
"price": "14.99",
"imageUrl": "https://cdn.shopify.com/coffee-medium.jpg"
}
]
},
"subscription": {
"subscriptionPlanId": 98765,
"sellingPlanGroupId": "gid://shopify/SellingPlanGroup/123456",
"frequencies": [
{
"interval": "MONTH",
"intervalCount": 1,
"displayName": "Deliver every month"
},
{
"interval": "WEEK",
"intervalCount": 2,
"displayName": "Deliver every 2 weeks"
}
]
}
}

Response Fields

Field	Description
`bundle.minProductCount`	Minimum number of products customers must select
`bundle.maxProductCount`	Maximum number of products customers can select
`bundle.discount`	Discount value applied to the bundle
`bundle.discountType`	Discount type (Percentage or Fixed Amount)
`bundle.allowOneTimePurchase`	Indicates whether one-time purchases are allowed
`bundle.products`	Products and variants available in the Build-a-Box
`subscription.frequencies`	Available subscription delivery frequencies

Available API Endpoints

The External API also supports creating and managing Build-a-Box bundles.

Action	Method	Endpoint
Get bundle by Handle	`GET`	`/api/external/v2/build-a-box/{handle}`
Get bundle by ID	`GET`	`/api/external/v2/build-a-box/{id}`
Create bundle	`POST`	`/api/external/v2/build-a-box`
Update bundle	`PUT`	`/api/external/v2/build-a-box`
Delete bundle	`DELETE`	`/api/external/v2/build-a-box/{id}`

All requests require the X-API-Key header.

Troubleshooting

401 Unauthorized

This usually means:

The X-API-Key header is missing.
The API key is invalid.
The API key has been regenerated or deleted.

Verify that you're sending the header exactly as:

X-API-Key: apst_xxxxxxxxxxxxxxxxxxxxxxxxx

404 Not Found

This typically indicates one of the following:

The Build-a-Box handle is incorrect.
The specified bundle does not exist.
The bundle is inactive or not properly configured.

Verify that the handle matches the one configured in your Appstle admin.

Can I call this API directly from my storefront?

We do not recommend calling this API directly from frontend JavaScript because it would expose your API key.

Instead:

Make the API request from your backend or server.
Return only the required bundle data to your storefront.
Render your custom Build-a-Box experience securely.

Need Help?

If you're experiencing issues accessing the API, contact the Appstle Support team and include:

Your Shopify shop domain
The Build-a-Box handle
The API endpoint you're calling
The response code or error message you're receiving

This information will help us troubleshoot your request more quickly.

Fetching Build-a-Box (Bundle) Configuration via API