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
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.
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
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.
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:
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.
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.
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).
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.
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.
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.
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
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.
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.
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
Bundles
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:
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:
When an order containing a bundle is placed, Zonos automatically:
Prerequisites
Before creating a bundle, ensure that:
Create a bundle
Every bundle must contain at least 2 component items. A single-item bundle should be a standalone catalog item instead.
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.
Bundle CSV fields
USD.1or2. Use the same number for all components in the same box.INCH.POUND.CSV import validation rules
The following validation rules apply to all bundle CSV imports:
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.
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:
USD.INCH.POUND.CN.POUND.INCH.USD.ASSIGNED_BOXfor items packed in the specified box,CONSOLIDATEDfor cartonization, orSHIPS_ALONEfor items that must ship separately. Optional — defaults toASSIGNED_BOXwhen box columns are present.Export bundles
Edit a bundle
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:
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.
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:
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
priceRatiocontrols 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:
Cartonization and labels
Assigned-box bundle components use merchant-defined boxes instead of the standard bin-packing algorithm. Each component's
packingPreferenceis set toASSIGNED_BOX, which tells cartonization to place it in the box specified bypackageOptionIdandpackageOptionIdIndex.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:
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:
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.
CatalogItemInput PackagingOptionCreateInput
catalogItemCreate catalogItemDelete catalogItemUpdate packagingOptionCreate
Was this page helpful?