DOCS

Kits

HomeGlobal ecommerce Catalog Kits

Kits

Sell bundled products with accurate landed cost based on merchant-defined boxes.

A kit is a product sold as a single (Parent) unit that breaks down into individual component items at checkout. The key benefits are an accurate landed cost — when a customer buys a kit, Zonos expands it into its components, discounts each component's price to match the bundle price, and calculates duties and taxes based on the actual boxes the merchant ships them in.

For example, a merchant sells shirts individually for $30 each, or as a kit of 4 for $100. When a customer buys the kit:

  • The order and commercial invoice show 4 shirts at $25 each (not 1 kit at $100 or 4 workout shirts for $30 each)
  • Each shirt's HS code and country of origin are used for the landed cost calculation
  • The shirts ship in merchant-defined boxes with known dimensions and weights, so the landed cost reflects real shipping costs

How kits work 

When you create a kit in Catalog, you define:

  • Kit SKU or product ID — the product identifier
  • Kit price - the total price as it appears in your store.
  • Component items — each individual product included in the kit, referenced by its catalog item ID. Components must already exist as catalog items before you can add them to a kit.
  • Box assignments — which components ship in which box. You define the boxes with real dimensions and weights so Zonos can calculate accurate shipping costs and landed cost.

When an order containing a kit is placed, Zonos automatically:

  1. Expands the kit into its individual components
  2. Discounts each component using computed price ratios so the per-item prices match the bundle price
  3. Calculates landed cost using each component's HS code, country of origin, and the merchant-defined box dimensions — giving an accurate duty, tax, and shipping total
  4. Generates labels for each box — each box gets its own shipping label

Prerequisites 

Before creating a kit, ensure that:

  • All component items exist as catalog items in your Zonos Catalog. The kit references components by their catalog item ID — you cannot add items that do not already exist. Components don't need to be sold individually in your store — they can exist in your catalog solely as kit parts.
  • Each component has accurate HS codes, country of origin, and measurements (weight and dimensions). These are used for landed cost calculations when the kit is expanded.
  • The kit's SKU or product ID matches the identifier your e-commerce platform sends to Zonos and the Item key preference in your Zonos Dashboard. For Shopify stores, the kit's product ID must be Shopify variant ID of the kit product.
  1. Go to Dashboard → Products → Kits.
  2. Click Add Kit in the top right corner.
  3. Enter the kit SKU or Product ID — this must match the identifier your store sends to Zonos. **Your Zonos Dashboards Item key preference must also be set to the correct identifier.
  4. Enter the kit name, price, and currency.
  5. Add component items by searching your catalog. For each component, specify:
    • Quantity — how many units of this component are in the kit
    • Box — which box this component ships in (add multiple boxes if your kit ships in more than one)
    • Price ratio — the portion of the kit price this component represents (used to calculate per-component declared values)
  6. Click Save.

To bulk-create kits by importing a CSV file:

  1. Click Manage Catalog → Import kits.
  2. Download the kit CSV template.
  3. Fill out one row per component item per box. Kit-level fields (SKU, name, price) repeat on every row for the same kit.
  4. Upload your completed CSV and click Import.

Kit CSV fields

Column↕Description↕
Kit SKUThe SKU of the kit as it appears in your store.
Kit Product IDThe product ID of the kit as it appears in your store.
Kit NameThe name of the kit.
Kit DescriptionA description of the kit.
Kit Image URLImage URL for the kit.
Kit AmountThe total price of the kit.
Kit CurrencyThe currency of the kit price, e.g., USD.
Box NumberThe box number this row's component ships in, e.g., 1 or 2. Use the same number for all components in the same box.
Box LengthLength of the box for this row.
Box WidthWidth of the box for this row.
Box HeightHeight of the box for this row.
Box Dimensional UnitDimensional unit for the box, e.g., INCH.
Box Weight CapacityMaximum weight capacity of the box.
Box Weight UnitWeight unit for the box capacity, e.g., POUND.
Item SKUThe SKU of this component item. Must match an existing catalog item.
Item Product IDThe product ID of this component item. Must match an existing catalog item.
Item QuantityHow many units of this component are in the kit.

Note: Edits to a kit affect future orders only. Orders already placed and fulfilled are not affected.

  1. Go to Dashboard → Products → Catalog.
  2. Select the Kits tab.
  3. Click the kit you want to edit.
  4. Update the fields and click Save.

To delete a single kit, open the kit and click Delete.

To delete multiple kits at once:

  1. Select the kits you want to delete using the checkboxes.
  2. Click Delete selected.
  3. Confirm the deletion.

To delete all kits on the current page, click Manage → Delete page.

Kit export uses the same catalogItemExportJobCreate mutation as regular catalog item export, filtered to itemType: BUNDLE.

  1. Go to Dashboard → Products → Catalog.
  2. Select the Kits tab.
  3. Click Manage → Export all.
  4. The export CSV will be emailed to you when ready.

Why kits matter for landed cost 

Without kits, Zonos sees a single line item (e.g., "Truck Tire 4-Pack — $1,000") with no visibility into what's inside. This causes problems:

  • No per-item HS codes — Zonos can't classify the components for accurate duty rates
  • No real box dimensions — shipping costs are estimated using the auto-packing algorithm instead of the merchant's actual boxes
  • No per-item pricing — the full bundle price is used for duty calculations instead of the discounted per-component price

Kits solve all three by giving Zonos the component breakdown, box assignments, and price allocation up front. The result is a landed cost quote that reflects what the customer will actually pay at the border.

Price ratios and component pricing 

The priceRatio on each component determines how the kit's total price is split across items. This affects the declared value on the commercial invoice and the duty/tax calculation for each component.

For example, a $1,000 kit with 4 tires at equal ratios (0.25 each) declares each tire at $250. If instead the kit contained 2 premium tires and 2 standard tires, you might set ratios of 0.35 and 0.15 respectively to reflect the actual value difference.

Zonos automatically normalizes ratios:

  • If ratios sum to more than 1.0, they are scaled down proportionally
  • If some components have no ratio set, the remainder after accounting for set ratios is distributed evenly among them
  • The final ratios always sum to exactly 1.0

Cartonization and labels 

Kit components use merchant-defined boxes instead of the standard bin-packing algorithm. Each component's packingPreference is set to ASSIGNED_BOX, which tells cartonization to place it in the box specified by packageOptionId and packageOptionIdIndex.

This is the core advantage of kits — the merchant knows exactly how their product ships, so the box dimensions and weights used for the landed cost calculation are accurate, not estimated.

Each box in a kit generates its own shipping label with its own tracking number. A kit with two boxes produces two labels. Non-kit items in the same order are packed separately using the standard cartonization algorithm.

Mixed kit orders 

A single order can contain multiple kits and standalone items simultaneously. For example, an order with:

  • 1x 4-pack kit (ships in 2 boxes)
  • 1x 2-pack kit (ships in 1 box)
  • 1x single item (ships in 1 box)

Zonos expands each kit independently. The landed cost calculation covers all 4 boxes with accurate dimensions and all 7 individual component prices. Each box gets its own label.

Shopify integration 

Kits have specific behavior when used with Shopify stores.

Setup

The kit's product ID in Zonos Catalog must match the Shopify variant ID of the kit product. This is how Zonos matches the Shopify line item to the kit definition. You can find the variant ID in the Shopify admin URL when viewing the product variant.

Order flow

When a customer orders a kit on a Shopify store:

  1. Shopify sends a single line item for the kit parent (e.g., "Truck Tire 4-Pack x 1").
  2. Zonos matches the line item's variant ID to the kit's product ID in your catalog.
  3. Zonos expands the kit into its individual components for the landed cost calculation — each component's HS code, country of origin, and discounted price are used for accurate duties and taxes.
  4. The Shopify order still shows the single kit line item — component expansion is handled entirely by Zonos.

Fulfillment

When creating fulfillments, Zonos maps the expanded kit components back to the original Shopify kit line item. The merchant sees the kit parent fulfilled in Shopify (e.g., "Truck Tire 4-Pack x 1 fulfilled"), while the commercial invoice and customs documents list each component separately.

GraphQL API ReferenceTypes, inputs, and operations used in this guide
INPUTS

CatalogItemExportJobCreateInput CatalogItemInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemExportJobCreate catalogItemUpdate

Book a demo

Was this page helpful?

Get support·Legal docs·© 2026 Zonos
On this page:
  • Kits
  • How kits work
  • Prerequisites
  • Create a kit
  • Edit a kit
  • Delete a kit
  • Export kits
  • Why kits matter for landed cost
  • Price ratios and component pricing
  • Cartonization and labels
  • Mixed kit orders
  • Shopify integration