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
- Go to Dashboard > Products > Bundles.
- Click Manage > Export.
- Choose an export option:
- Export all bundles — exports every bundle
- Export assigned box bundles — exports only bundles with pre-assigned boxes
- Export auto bundles — exports only auto-box bundles
- Click Export. The CSV will be emailed to you when ready.
Edit a bundle
Note: Edits to a bundle affect future orders only. Orders already placed and fulfilled are not affected.
- Go to Dashboard > Products > Bundles.
- Click the bundle you want to edit.
- Update the fields and click Save.
You can change packing mode, add or remove components, update box assignments, and modify the bundle price.
Delete a bundle
To delete a single bundle, open the bundle and click Delete.
To delete multiple bundles at once:
- Select the bundles you want to delete using the checkboxes.
- Click Delete selected.
- Confirm the deletion.
To delete all bundles on the current page, click Manage > Delete page.
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.
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: