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.

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 , the productPlatformId is 8978907431150.

Fetching Dynamic Build a Box data from the API

To add one-time upsells in a third-party Build-a-Box, use Shopify's Cart API 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:

{
  "productPlatformId": "7194276266047"
}

Data structure of the endpoint response

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

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

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.