Dynamic Box API guide for developers

This guide explains how to use the Skio Dynamic Build-a-Box 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.

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.