> ## 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.

# Retrieve Build-A-Box bundle details by handle

> Reads a Build-A-Box by its handle, which is the box's `uniqueRef` (the **Ref** column of the Appstle app's **Build-A-Box** list). This is an Admin API call for your server: never put the API key in theme or browser code.

The response holds the box in `bundle`, its plan group in `subscription` and the plan group's products in `products`. `bundle` is the body to send back to `PUT /api/external/v2/build-a-box`.

**Behavior:**
- The call answers `404` while the box is off, unless `thirdPartyRule` is `true`. To read a box that is off, use `GET /api/external/v2/build-a-box/{id}`.
- The call also answers `404` for a handle that isn't one of your boxes, and when the box's `subscriptionId` isn't one of your plan groups.
- A value made only of digits is read as an `id`, and any other value as a `uniqueRef`. A box read by its `id` comes back without the `bundle` wrapper, and a box whose `uniqueRef` is only digits can be read only by its `id`.

**Authentication:** Requires a valid `X-API-Key` header.



## OpenAPI

````yaml /subscription/admin-api-swagger.json get /api/external/v2/build-a-box/{handle}
openapi: 3.0.1
info:
  description: >-
    Comprehensive API documentation for managing subscriptions, payments, and
    related operations. These APIs allow you to programmatically manage
    subscription lifecycles, handle payments, configure products, and integrate
    subscription functionality into your applications.
  title: Admin APIs
  version: 0.0.1
servers:
  - url: https://subscription-admin.appstle.com
security: []
tags:
  - description: >-
      Core APIs for managing the complete subscription lifecycle including
      creation, updates, pausing, resuming, and cancellation of subscriptions.
    name: Subscription Management
  - description: >-
      APIs for managing subscription payment methods, processing payments,
      handling payment retries, and updating billing information.
    name: Subscription Payments
  - description: >-
      APIs for managing subscription contracts including delivery schedules,
      pricing, order notes, billing cycles, and shipping addresses.
    name: Subscription Contracts
  - description: >-
      APIs for managing products within subscriptions including adding,
      removing, updating quantities, and swapping products.
    name: Subscription Products
  - description: >-
      APIs for handling billing operations, payment processing, and financial
      transactions related to subscriptions.
    name: Billing & Payments
  - description: >-
      APIs for managing discounts and promotional codes applied to
      subscriptions.
    name: Subscription Discounts
  - description: >-
      APIs for managing one-time add-on products that can be purchased alongside
      recurring subscription items.
    name: Subscription One-Time Products
  - description: >-
      APIs for managing subscription plans, pricing tiers, and plan
      configurations.
    name: Subscription Plans
  - description: >-
      APIs for managing customizable product boxes and bundles where customers
      can select multiple items.
    name: Build-a-Box & Bundles
  - description: >-
      APIs for managing the product catalog including product information,
      variants, and inventory.
    name: Product Catalog
  - description: >-
      APIs for managing operational settings, configurations, and administrative
      functions.
    name: Operations & Settings
  - description: >-
      APIs powering the customer-facing portal where subscribers can manage
      their own subscriptions.
    name: Customer Portal
  - description: APIs for managing customer information, profiles, and account details.
    name: Customers
  - description: >-
      APIs for retrieving aggregated subscription data, customer subscription
      history, and account-level subscription information.
    name: Subscription Data
  - description: >-
      APIs for managing delivery profiles, shipping rates, free shipping
      configuration, and delivery method options on subscriptions.
    name: Delivery & Shipping
  - description: >-
      APIs for managing storefront customization including custom CSS, theme
      settings, label translations, and merchant-defined widget configuration.
    name: Customization
  - description: >-
      APIs for configuring cancellation flows, retention offers, cancellation
      reason management, and win-back automation.
    name: Customer Retention
paths:
  /api/external/v2/build-a-box/{handle}:
    get:
      tags:
        - Build-a-Box & Bundles
      summary: Retrieve Build-A-Box bundle details by handle
      description: >-
        Reads a Build-A-Box by its handle, which is the box's `uniqueRef` (the
        **Ref** column of the Appstle app's **Build-A-Box** list). This is an
        Admin API call for your server: never put the API key in theme or
        browser code.


        The response holds the box in `bundle`, its plan group in `subscription`
        and the plan group's products in `products`. `bundle` is the body to
        send back to `PUT /api/external/v2/build-a-box`.


        **Behavior:**

        - The call answers `404` while the box is off, unless `thirdPartyRule`
        is `true`. To read a box that is off, use `GET
        /api/external/v2/build-a-box/{id}`.

        - The call also answers `404` for a handle that isn't one of your boxes,
        and when the box's `subscriptionId` isn't one of your plan groups.

        - A value made only of digits is read as an `id`, and any other value as
        a `uniqueRef`. A box read by its `id` comes back without the `bundle`
        wrapper, and a box whose `uniqueRef` is only digits can be read only by
        its `id`.


        **Authentication:** Requires a valid `X-API-Key` header.
      operationId: getValidSubscriptionCustomerV2_2
      parameters:
        - description: Bundle Handle
          in: path
          name: handle
          required: true
          schema:
            type: string
        - description: API Key (Deprecated - Use Header X-API-Key instead)
          in: query
          name: api_key
          required: false
          schema:
            type: string
        - in: header
          name: X-API-Key
          required: false
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                Box that is on:
                  description: Box that is on
                  value:
                    bundle:
                      allowOneTimePurchase: false
                      buildABoxType: SINGLE_PRODUCT
                      bundleRedirect: CART
                      chooseProductsText: Pick your coffees
                      discount: 0
                      id: 21105
                      minOrderAmount: 0
                      minProductCount: 0
                      name: Roasters choice box
                      proceedToCheckoutButtonText: Go to cart
                      productViewStyle: QUICK_ADD
                      shop: your-store.myshopify.com
                      singleProductSettings: >-
                        [{"sourceProduct":{"id":15386745176368,"title":"Ethiopia
                        Coffee","handle":"ethiopia-coffee"},"minQuantity":"1","maxQuantity":"2","products":[{"id":15386745078064,"type":"PRODUCT","title":"Colombia
                        Coffee","productHandle":"colombia-coffee","status":"ACTIVE"}]}]
                      subscriptionBundlingEnabled: true
                      subscriptionId: 80297427248
                      trackInventory: false
                      uniqueRef: hi7utqdu
                    products:
                      - productHandle: house-blend-coffee
                        productId: 15386633601328
                        productTitle: House Blend Coffee
                    subscription:
                      groupName: Coffee Subscription
                      id: 284357
                      productCount: 8
                      subscriptionId: 80297427248
              schema:
                $ref: '#/components/schemas/SubscriptionBundlingResponseV3'
          description: >-
            The box, in `bundle`, with its plan group and the plan group's
            products
        '401':
          description: The `X-API-Key` header is missing, or the key isn't valid.
        '404':
          description: >-
            The box is off, the handle isn't one of your boxes, or the box's
            `subscriptionId` isn't one of your plan groups. The body is empty.
components:
  schemas:
    SubscriptionBundlingResponseV3:
      properties:
        bundle:
          $ref: '#/components/schemas/SubscriptionBundling'
        products:
          items:
            $ref: '#/components/schemas/ProductInfo'
          type: array
        subscription:
          $ref: '#/components/schemas/SubscriptionGroupPlan'
        subscriptionGroupPlans:
          items:
            $ref: '#/components/schemas/SubscriptionGroupPlan'
          type: array
        subscriptionPlanProductInfoMap:
          additionalProperties:
            items:
              $ref: '#/components/schemas/ProductInfo'
            type: array
          type: object
        subscriptionPlanVariantMap:
          additionalProperties:
            items:
              type: string
            type: array
          type: object
        variants:
          items:
            type: string
          type: array
      type: object
    SubscriptionBundling:
      properties:
        allowOneTimePurchase:
          type: boolean
        appliesOn:
          enum:
            - PRODUCT
            - COLLECTION
            - BOTH
            - ONE_TIME
            - SUBSCRIPTION
          type: string
        buildABoxType:
          enum:
            - 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
          type: string
        bundleBottomHtml:
          type: string
        bundleRedirect:
          enum:
            - CART
            - CART_DRAWER
            - CHECKOUT
            - CUSTOM
            - NONE
          type: string
        bundleTopHtml:
          type: string
        chooseProductsText:
          type: string
        collectionData:
          type: string
        customRedirectURL:
          type: string
        discount:
          format: double
          type: number
        discountedVariants:
          type: string
        id:
          format: int64
          type: integer
        inventoryTrackingMode:
          enum:
            - ADD_CHILD_PRODUCT_ON_ORDER
            - ADD_CHILD_PRODUCT_ON_CHECKOUT
          type: string
        maxProductCount:
          format: int32
          type: integer
        minOrderAmount:
          format: double
          type: number
        minProductCount:
          format: int32
          type: integer
        minUniqueProductCheck:
          type: boolean
        name:
          type: string
        proceedToCheckoutButtonText:
          type: string
        productDiscountType:
          enum:
            - SELECTED_PRODUCT
            - EACH_PRODUCT
          type: string
        productSelectionType:
          enum:
            - PRODUCT
            - COLLECTION
          type: string
        productViewStyle:
          enum:
            - QUICK_ADD
            - VIEW_DETAILS
          type: string
        sections:
          type: string
        selectionType:
          enum:
            - FIXED
            - FLEXIBLE
          type: string
        sellingPlanIds:
          type: string
        shop:
          type: string
        singleProductSettings:
          type: string
        subscriptionBundlingEnabled:
          type: boolean
        subscriptionGroup:
          type: string
        subscriptionId:
          format: int64
          type: integer
        thirdPartyRule:
          type: boolean
        tieredDiscount:
          type: string
        trackInventory:
          type: boolean
        uniqueRef:
          type: string
        variants:
          type: string
      required:
        - shop
      type: object
    ProductInfo:
      properties:
        id:
          format: int64
          type: integer
        productHandle:
          type: string
        productId:
          format: int64
          type: integer
        productTitle:
          type: string
        shop:
          type: string
      required:
        - shop
      type: object
    SubscriptionGroupPlan:
      properties:
        groupName:
          type: string
        id:
          format: int64
          type: integer
        infoJson:
          type: string
        productCount:
          format: int32
          type: integer
        productIds:
          type: string
        productVariantCount:
          format: int32
          type: integer
        shop:
          type: string
        subscriptionId:
          format: int64
          type: integer
        translations:
          type: string
        variantIds:
          type: string
        variantProductIds:
          type: string
      required:
        - shop
      type: object

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.