Base URL
All Bundles endpoints currently use this host:/api/external/. Storefront endpoints are documented in the generated Storefront API reference.
Every Admin API endpoint takes only
GET. A GET to a path under /api/external/ that has no endpoint returns 404 with an application/problem+json body, and a POST, PUT or DELETE returns 405 with Request method 'PUT' not supported (or 'POST', 'DELETE'). If you get a 404 or a 405, check the path and the method against the API reference.Authentication
- Admin API
- Storefront API
Direct backend integrations pass the merchant’s API key in the Keep this key server-side only.
X-API-Key header.Admin API endpoints
Get bundle rules
Returns every bundle rule in the store, of every type.Get discount rules
Returns only the rules whosebundleType is VOLUME_DISCOUNT, DISCOUNTED_PRICING, BUY_X_GET_Y or SHIPPING_DISCOUNT.
Get build-a-box rules
Returns only the rules whosebundleType is CLASSIC, CLASSIC_BUILD_A_BOX, SINGLE_PRODUCT_BUILD_A_BOX or SECTIONED_BUNDLE.
Filter and page the lists
/bundle-rules, /bundle-rules/bab and /bundle-rules/discount take the same filters and paging. A filter is written field.operator=value, for example status.equals=ACTIVE. The reference lists every field you can filter on and the operators each field takes. Filters on different fields combine, so a rule must match all of them. Leave shop out: the store always comes from your API key.
For a date-time field, send the value with its zone, such as
2026-01-01T00:00:00Z. A date alone, such as 2026-01-01, returns 400.
On a text field, or a field with a fixed list of values such as status, send one operator. If you send two on the same field, such as name.contains=box&name.doesNotContain=gift, only one of them is applied. Number and date-time fields combine their operators, so id.greaterThan=1000&id.lessThan=2000 is a range.
On /bundle-rules/bab and /bundle-rules/discount, a bundleType filter replaces the endpoint’s own list of types instead of narrowing it: /bundle-rules/bab?bundleType.equals=VOLUME_DISCOUNT returns volume discount rules. To narrow those endpoints by type, use bundleType.in with types from the endpoint’s list.
A filter the API doesn’t recognize returns
400: a misspelled field (stauts.equals), a misspelled operator (status.equal), an operator the field doesn’t take (status.contains), or the bracket form (status[equals]=ACTIVE). The message says how to write the filter, and for an operator it lists the ones the field takes. A parameter with no dot that isn’t a field you can filter on, such as stauts=ACTIVE, isn’t checked: the API ignores it, as if you hadn’t sent it. Copy parameter names from the reference, and check x-total-count when a filter seems to have no effect.id first). The sort parameter in the reference is accepted but doesn’t change the order. page starts at 0. size defaults to 20 and is capped at 2000. This request reads the second page of active rules, three at a time:
x-total-count is the number of matching rules. link always has first and last, plus next when a later page exists and prev when an earlier one does. With no matches, x-total-count is 0 and last points to page=-1.
Whenever your request percent-encodes a value, as
--data-urlencode does with the comma in an in list, page with page and x-total-count instead of the link URLs. Those URLs encode the value a second time (%2C becomes %252C), so an in or notIn list returns 400 and a text filter such as name.contains quietly matches different rules. Send the same filters with page set to the next number, and stop when a page comes back with fewer than size rules or when you have read x-total-count rules.Handle a 400 from a filter
A filter name the API doesn’t recognize, a filter value it can’t read, or a field sent without an operator comes back as400 with a violations list that names each parameter at fault:
violations[].field to see which parameter to fix. The message says what is wrong: a field sent without an operator, an unknown field or operator, the bracket form, a value of the wrong type (such as a date without a time), or a value outside a fixed list, such as an unknown bundleType. For an unknown operator, the message lists the operators the field takes. For a value outside a fixed list, it lists the allowed values. Fix the request and send it again. Don’t retry it unchanged.
Storefront API endpoints
Use the Storefront API reference for exact schemas. The main categories are:Build-a-box lookup
Build-a-box lookup
Fetch build-a-box configuration by token, handle, or single-product context so a custom storefront can render the correct bundle experience.
Discount generation
Discount generation
Generate bundle discounts and shipping discounts for eligible build-a-box selections.
Visitor activity
Visitor activity
Ping visitor activity for Appstle storefront bundle widgets and customer-facing flows.
Production checklist
- Keep Admin API keys server-side.
- Cache bundle-rule reads where possible; merchant configuration changes less frequently than storefront traffic.
- Treat Storefront API token parameters as flow-specific and avoid hard-coding them across shops.
- Implement retries with exponential backoff for
429and transient5xxresponses. - Log request IDs and response status codes for merchant-support debugging.