---
title: "Dynamic Box API guide for developers"
slug: "dynamic-box-api-guide-for-developers"
description: "Learn to implement Skio's Dynamic feature with a custom frontend flow via API, enhancing your Build-a-Box experience with developer insights."
updated: 2026-04-20T15:10:05Z
published: 2026-04-20T15:10:05Z
stale: true
---

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

# Dynamic Box API guide for developers

This guide explains how to use the Skio Dynamic feature with a custom frontend flow via API, rather than using Skio's default Build-a-Box interface. For documentation on the standard Dynamic Build a Box setup, see [Dynamic Build-a-Box Setup Guide](/help/docs/dynamic-build-a-box-setup-guide).

> [!CAUTION]
> This guide involves custom coding and API integration. Developer experience is required to implement this solution.

## Finding the Dynamic Box Product ID

To use the Dynamic Box API, you'll need the `productPlatformId` for your box.

To find it:

1. Go to your Skio dashboard and navigate to **Acquire** > **Build-a-Box**
2. Scroll to the Dynamic Box you want to use
3. Click the kebab menu, then select **Customer View**
4. Copy the product ID from the URL

For example, if your preview URL is: [https://yourstore.com/a/account/build-a-box/dynamic/8978907431150](https://yourstore.com/a/account/build-a-box/dynamic/8978907431150) , the `productPlatformId` is 8978907431150.

![](https://cdn.us.document360.io/a953bba6-c70d-43ce-bc77-d7f32a8fc514/Images/Documentation/CleanShot 2026-04-20 at 11.06.14.png)

## Fetching Dynamic Build a Box data from the API

> [!NOTE]
> To add one-time upsells in a third-party Build-a-Box, use [Shopify's Cart API](https://shopify.dev/docs/api/ajax/reference/cart) to add OTU items directly.

**Endpoint:** `https://api.skio.com/storefront-http/get-dynamic-box`

Send a POST request with a JSON body like the example below:

```json
{
  "productPlatformId": "7194276266047"
}
```

### Data structure of the endpoint response

```typescript
{
  boxId: string;
  platformId: string;
  title: string;
  currencyCode: string;
  imageSrc: string;
  fixedDiscountTier?: { [size: string]: string };
  percentDiscountTier?: { [size: string]: string };
  sizeRange?: number[];
  sizeInterval?: number[];
  selectableProductVariants: SelectableProductVariantCustomize[];
  sellingPlanGroup?: DynamicBoxSellingPlanGroup;
};

SelectableProductVariantCustomize = {
  productTitle: string;
  productImageSrc: string;
  productPlatformId: string;
  productHandle: string;
  productVariants: {
    platformId: string;
    productVariantTitle: string;
    imageSrc: string;
    price: number;
    customLabel?: string[];
  }[];
};

DynamicBoxSellingPlanGroup = {
  [planId: string]: {
    title?: string;
    interval: SellingPlanInterval;
    intervalCount: number;
    priceAdjustmentType: SellingPlanPricingPolicyAdjustmentType;
    priceAdjustmentAmount: number;
    variantMapping: ChildVariantPlanMapping;
    allMatch?: boolean; // If all child variants with same selling plan interval have the same pricing policy
  }
};
```

## Building your custom flow and passing customer selections through checkout

As the developer, you'll need to implement the user experience for selecting box items. Once the customer has made their selections, you'll pass those choices through checkout by calling the Shopify cart API to add the items with the following custom properties.

### Adding to Cart

For Skio's backend to recognize that a Build-a-Box (BAB) has been added to cart, specific line item properties must be included with each product in a dynamic Build a Box.

#### Required Line Item Properties

| Property | Type | Description |
| --- | --- | --- |
| `_dynamicBoxId` | String | The ID of the box. |
| `_dynamicBoxIndex` | Number | Differentiates between multiple boxes with the same ID in the cart. Set to `0` for the first box, `1` for a second box with the same ID, and so on. |

#### Example

```json
{
  "quantity": 1,
  "id": 12345678,
  "selling_plan": 87654321,
  "properties": {
    "_dynamicBoxId": "box_abc123",
    "_dynamicBoxIndex": 0
  }
}
```

> [!NOTE]
> In most cases, `_dynamicBoxIndex` should be set to `0`. Only increment it when a customer adds multiple boxes with the same `_dynamicBoxId` to their cart.