> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Appstle Bundles: Build-a-Box and Bundle Rules

> Appstle Bundles provides Admin and Storefront REST APIs to read bundle rules, power build-a-box experiences, and generate bundle discounts on Shopify.

Appstle Bundles helps Shopify merchants create bundle offers, build-a-box flows, and discount experiences. Read configured bundle rules from your server, render build-a-box experiences from the storefront, and — when you want full control of the look and feel — run Appstle's fixed pricing, dynamic pricing, and volume discount bundles with your own custom storefront UI.

<Card title="Build bundles with your own storefront UI" icon="paintbrush" href="/bundles/headless-overview">
  Prefer your own design over Appstle's built-in widgets? Read the bundle rule over the API, render your own selector, and let Appstle's automatic discount apply the savings at checkout. Start with the headless overview.
</Card>

## Available APIs

Appstle Bundles exposes two REST API surfaces. Pick the one that matches where your code runs:

* **Admin API** — server-side, authenticated with `X-API-Key`. For reading configured bundle and discount rules from a backend service. Browse the full reference under **Admin API** in the sidebar.
* **Storefront API** — customer-facing, accessed through Shopify App Proxy. For rendering build-a-box experiences and generating bundle discounts. Browse the full reference under **Storefront API** in the sidebar.

## Which API should you use?

<Tabs>
  <Tab title="Use the Admin API when…">
    * You need to **read configured bundle rules** from a backend service
    * You need to **read bundle discount rules**
    * You are **syncing build-a-box rules** into another system
    * You are building **reporting, auditing, or merchant-support tooling**
    * Your code runs **anywhere outside a customer's browser** on the storefront

    <Info>
      Admin API requests require an `X-API-Key` header. Keys are created in the Appstle dashboard under **Settings → API Key Management**. Never expose keys in client-side code.
    </Info>
  </Tab>

  <Tab title="Use the Storefront API when…">
    * You are **rendering build-a-box pages** on your storefront
    * You are **looking up bundle configuration** by token or product handle
    * You are **generating bundle and shipping discounts** for a selection
    * You are sending **storefront widget activity** calls

    <Warning>
      Storefront endpoints run through Shopify's App Proxy and are intended for storefront flows. For backend integrations, use the Admin API instead.
    </Warning>
  </Tab>
</Tabs>

## Key features

<CardGroup cols={2}>
  <Card title="Bundle rule lookup" icon="boxes-stacked">
    Read active bundle rules and discount rules for a store so external systems can mirror merchant configuration.
  </Card>

  <Card title="Build-a-Box experiences" icon="box-open">
    Fetch build-a-box configuration by token or product handle and render bundle selectors in custom storefronts.
  </Card>

  <Card title="Bundle discounts" icon="tag">
    Generate bundle and shipping discounts for eligible build-a-box selections.
  </Card>

  <Card title="Storefront activity" icon="signal">
    Record storefront visitor activity for Appstle-powered bundle widgets and customer-facing flows.
  </Card>
</CardGroup>

## Base URL

All Admin API endpoints use:

```
https://bundles-admin.appstle.com
```

Storefront API endpoints are accessed through your store's Shopify App Proxy — no separate base URL is needed.

## HTTP status codes

All API responses use standard HTTP status codes.

| Code  | Meaning                                    |
| ----- | ------------------------------------------ |
| `200` | Success                                    |
| `400` | Bad request — invalid parameters           |
| `401` | Unauthorized — missing or invalid API key  |
| `403` | Forbidden — key lacks required permissions |
| `404` | Not found                                  |
| `429` | Rate limit exceeded                        |
| `500` | Server error                               |

Error responses follow this shape:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API key provided",
  "status": 401
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/bundles/authentication">
    Create an API key and learn how to authenticate server-side Bundles API calls.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/bundles/quickstart">
    Get an API key and make your first bundle-rule request.
  </Card>

  <Card title="Integration guide" icon="book" href="/bundles/integration-guide">
    Review the main Admin and Storefront endpoint categories.
  </Card>
</CardGroup>