Bundles

Sell bundled products with accurate landed cost and flexible packing options.

A bundle is a product sold as a single (parent) unit that breaks down into individual component items at checkout. When a customer buys a bundle, Zonos expands it into its components, discounts each component's price to match the bundle price, and calculates duties and taxes based on each component's HS code and country of origin.

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

The order and commercial invoice show 4 shirts at $25 each (not 1 bundle at $100 or 4 shirts at $30 each)
Each shirt's HS code and country of origin are used for the landed cost calculation
Shipping costs are calculated using the actual box dimensions the merchant ships them in

Packing modes

Bundles support two packing modes that control how items are boxed for shipping:

Assigned box

The merchant pre-assigns items to specific boxes with known dimensions. Each box is defined with length, width, height, and weight capacity. Cartonization uses these exact boxes instead of estimating.

Best for: Products where you know which box they ship in, or bundles that always ship in the same box.

Auto-box

The merchant groups items into a bundle without specifying boxes. At order time, Zonos uses its cartonization algorithm to determine optimal box packing based on the items' dimensions and available packaging options.

Best for: Bundles where the packing varies, products with flexible packaging, or when you want Zonos to optimize box selection automatically.

Both modes expand the bundle into individual components with per-item HS codes, country of origin, and discounted pricing. The difference is only in how boxes are determined.

How bundles work

When you create a bundle in Catalog, you define:

Bundle SKU or product ID — the product identifier that matches your store
Bundle price — the total price as it appears in your store
Packing mode — assigned box or auto-box
Component items — each individual product included in the bundle, referenced by its catalog item ID. Components must already exist as catalog items before you can add them to a bundle.
Box assignments (assigned box only) — which components ship in which box, with real dimensions and weights

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

Expands the bundle into its individual components
Discounts each component using computed price ratios so the per-item prices match the bundle price
Calculates landed cost using each component's HS code, country of origin, and box dimensions — giving an accurate duty, tax, and shipping total
Generates labels — assigned-box bundles get one label per defined box; auto-box bundles get labels based on cartonization results

Prerequisites

Before creating a bundle, ensure that:

All component items exist as catalog items in your Zonos Catalog. The bundle 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 bundle parts.
Each component has accurate HS codes, country of origin, and measurements (weight and dimensions). These are used for landed cost calculations when the bundle is expanded.
The bundle'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 bundle's product ID must be the Shopify variant ID of the bundle product.

Create a bundle

Every bundle must contain at least 2 component items. A single-item bundle should be a standalone catalog item instead.

Go to Dashboard > Products > Bundles.
Click Add Bundle in the top right corner.
Enter the bundle SKU or Product ID — this must match the identifier your store sends to Zonos. Your Zonos Dashboard's Item key preference must also be set to the correct identifier.
Enter the bundle name, price, and currency.
Select Assigned box as the packing mode.
Add boxes with specific dimensions (length, width, height, and weight capacity).
Add component items by searching your catalog and assign each one to a box. For each component, specify:
- Quantity — how many units of this component are in the bundle
- Box — which box this component ships in
- Price ratio — the portion of the bundle price this component represents (auto-calculated if left blank)
Click Save.

Import bundles via CSV

There are two import options available from Manage > Import:

Import bundles

Creates bundles that reference existing catalog items. Component items must already exist in your catalog before importing.

Go to Dashboard > Products > Bundles.
Click Manage > Import bundles.
Download a sample CSV template — choose Assigned box or Auto-box format.
Fill out one row per component item. Bundle-level fields (SKU, name, price) repeat on every row for the same bundle.
Upload your completed CSV and click Import.

Bundle CSV fields

Column↕	Description↕
Bundle SKU	The SKU of the bundle as it appears in your store.
Bundle Product ID	The product ID of the bundle as it appears in your store.
Bundle Name	The name of the bundle.
Bundle Description	A description of the bundle.
Bundle Image URL	Image URL for the bundle.
Bundle Amount	The total price of the bundle.
Bundle Currency	The currency of the bundle price, e.g., `USD`.
Box Number	The 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 Length	Length of the box for this row.
Box Width	Width of the box for this row.
Box Height	Height of the box for this row.
Box Dimensional Unit	Dimensional unit for the box, e.g., `INCH`.
Box Weight Capacity	Maximum weight capacity of the box.
Box Weight Unit	Weight unit for the box capacity, e.g., `POUND`.
Item SKU	The SKU of this component item. Must match an existing catalog item.
Item Product ID	The product ID of this component item. Must match an existing catalog item.
Item Quantity	How many units of this component are in the bundle.

Note: Both "Bundle" and "Kit" column prefixes are accepted for backwards compatibility (e.g., "Kit SKU" works the same as "Bundle SKU").

CSV import validation rules

The following validation rules apply to all bundle CSV imports:

Minimum 2 items — Every bundle must contain at least 2 component items. A single-item bundle should be a standalone catalog item instead.
All-or-nothing box fields — For assigned-box bundles, all 6 box fields must be present on every row: Box Length, Box Width, Box Height, Box Dimensional Unit, Box Weight Capacity, and Box Weight Unit. If any box field is set, all 6 are required. If all box fields are empty, the bundle is treated as auto-box.
No mixing packing modes — A single bundle cannot mix assigned-box rows (with box dimensions) and auto-box rows (without box dimensions). All rows for one bundle must use the same mode.
HS code normalization — HS codes are automatically formatted on import. Non-alphanumeric characters (dots, dashes, spaces) are stripped and the code is normalized to an even-digit format.

Import bundles + catalog items

Creates both catalog items AND bundles in a single upload. Use this when your component items don't already exist in the catalog — they will be created or updated automatically.

Go to Dashboard > Products > Bundles.
Click Manage > Import bundles + catalog items.
Download a sample CSV template — choose Assigned box or Auto-box format.
Fill out one row per component item, including item detail columns (name, HS code, country of origin, measurements).
Upload your completed CSV and click Import.

The import first creates or updates the child catalog items, then creates the bundles referencing them. If an item with the same SKU or product ID already exists, its details are updated with the values from the CSV. HS codes are automatically normalized during import (non-alphanumeric characters are removed and the code is formatted to the standard even-digit format).

Combined CSV fields

Includes all bundle CSV fields plus item detail columns:

Column↕	Description↕
Bundle SKU	The SKU of the bundle.
Bundle Product ID	The product ID of the bundle.
Bundle Name	The name of the bundle.
Bundle Description	A description of the bundle.
Bundle Image URL	Image URL for the bundle.
Bundle Amount	The total price of the bundle.
Bundle Currency	The currency of the bundle price, e.g., `USD`.
Box Number	Which box this component ships in.
Box Length	Length of the box.
Box Width	Width of the box.
Box Height	Height of the box.
Box Dimensional Unit	Dimensional unit, e.g., `INCH`.
Box Weight Capacity	Weight capacity of the box.
Box Weight Unit	Weight unit, e.g., `POUND`.
Item SKU	The SKU of the component item.
Item Product ID	The product ID of the component item.
Item Name	Display name for the catalog item.
Item Description	Description of the item.
Item HS Code	Harmonized System code for customs classification.
Item Country of Origin	Two-letter country code where the item is manufactured, e.g., `CN`.
Item Weight	Weight of the item.
Item Weight Unit	Weight unit, e.g., `POUND`.
Item Length	Length of the item.
Item Width	Width of the item.
Item Height	Height of the item.
Item Dimensional Unit	Dimensional unit for item measurements, e.g., `INCH`.
Item Quantity	How many units of this component are in the bundle.
Item Amount	The price of the individual component item. Used when creating or updating the catalog item.
Item Currency	The currency of the item price, e.g., `USD`.
Item Packing Preference	How this item should be packed. Use `ASSIGNED_BOX` for items packed in the specified box, `CONSOLIDATED` for cartonization, or `SHIPS_ALONE` for items that must ship separately. Optional — defaults to `ASSIGNED_BOX` when box columns are present.

Export bundles

Edit a bundle

Delete a bundle

Use bundles in the quoter

You can add bundles to a quote directly from the quoter to preview the landed cost before placing an order.

In the quoter, switch to the Search bundles tab in the Items section.
Search for a bundle by name, SKU, or product ID.
Select a bundle. Zonos automatically:
- Expands the bundle into individual component items in the item list, each with its own HS code, country of origin, and discounted price.
- Populates boxes (assigned-box bundles only) — the bundle's pre-defined boxes are added to the Boxes section with their dimensions pre-filled.
- Skips box population (auto-box bundles) — cartonization determines boxes when the quote is calculated.
Component items appear grouped under the bundle name in the item list.
Calculate the quote. The landed cost reflects the actual bundle structure — per-component duties, taxes, and shipping based on real or auto-determined box dimensions.

You can add multiple bundles and standalone items to the same quote. Each bundle expands independently.

Why bundles matter for landed cost

Without bundles, 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

Bundles solve all three by giving Zonos the component breakdown, box assignments (or auto-box grouping), 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

When a bundle is sold, Zonos needs to know how much each component is worth individually. This is because international shipments require a declared value per item on the commercial invoice, and duty/tax is calculated on each item separately.

The priceRatio controls how the bundle's total price is split across its components. You don't have to set this yourself — if you leave it blank, Zonos automatically splits the price evenly across all components.

For example, a $1,000 bundle with 4 tires and no price ratios set would automatically declare each tire at $250 (0.25 each). If your components have different values — say 2 premium tires and 2 standard tires — you can manually set ratios like 0.35 and 0.15 to reflect the actual value difference.

Zonos automatically normalizes ratios so you don't have to worry about the math:

If you leave some ratios blank, the remaining value is split evenly among those components
If ratios don't add up to exactly 1.0, Zonos scales them proportionally
The final ratios always sum to exactly 1.0

Cartonization and labels

Assigned-box bundle 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 assigned-box bundles — 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 bundle generates its own shipping label with its own tracking number. A bundle with two boxes produces two labels.

Mixed orders

Non-bundle items in the same order are packed separately using the standard cartonization algorithm, regardless of which packing mode the bundles use.

Mixed bundle orders

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

1x 4-pack bundle with assigned boxes (ships in 2 boxes)
1x 3-item auto-box bundle (cartonization determines packing)
1x single standalone item

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

Shopify integration

Bundles have specific behavior when used with Shopify stores.

Setup

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

Order flow

When a customer orders a bundle on a Shopify store:

Shopify sends a single line item for the bundle parent (e.g., "Truck Tire 4-Pack x 1").
Zonos matches the line item's variant ID to the bundle's product ID in your catalog.
Zonos expands the bundle 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.
The Shopify order still shows the single bundle line item — component expansion is handled entirely by Zonos.

Fulfillment

When creating fulfillments, Zonos maps the expanded bundle components back to the original Shopify bundle line item. The merchant sees the bundle 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

CatalogItemInput PackagingOptionCreateInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemUpdate packagingOptionCreate

Book a demo