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 order creation. When a customer buys a bundle, Zonos expands it into its components, scales each component's price so that the total matches the parent bundle price, and calculates duties and taxes based on each individual component.
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
**Incorrect information on the commercial invoice - the commercial invoice will show 1 item instead of each invidiual item
**Generic packing slips - packing slips do not show each item to go in the order just single line item for the entire bundle
Bundles solve all five by giving Zonos the component breakdown, box assignments (or auto-box grouping), and price allocation up front. The result is a landed cost quote, commerical 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.
The bundle's product ID in Zonos Catalog must match the Shopify variant
ID of the bundle product. Use the numeric variant ID only (e.g.,
45271622844730), not the full GraphQL ID. You can find the variant ID in the
Shopify admin URL when viewing the product variant.
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.
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.
Shopify items flagged as non-shippable (digital downloads, gift cards, etc.)
are automatically excluded from the landed cost calculation. If a bundle
contains a mix of physical and digital components, only the physical components
are sent to Zonos for rating and fulfillment.
The bundle's SKU or product ID in Zonos Catalog must match the
BigCommerce product identifier. BigCommerce product IDs are numeric only
(e.g., 12345), so ensure the product ID in your Zonos bundle definition is
the numeric BigCommerce product ID. BigCommerce natively separates cart items
into physical items and digital items, which affects how bundles with
mixed content are handled.
BigCommerce supports digital items —
for example, a digital editing software download. Because BigCommerce sends
access to digital goods upon fulfillment digital goods cannot be included as
part of the bundle defintion in Zonos. The best solution is usually to price the
physical goods in the bundle as the full price of the bundle and then create A
promotional rule in Bigcommerce to include the digital items when ever the bundle
is in the cart.
BigCommerce handles digital item delivery (email/download) separately from
physical fulfillment. Physical bundle components are fulfilled through Zonos
with shipping labels and tracking. Digital items are delivered by BigCommerce
automatically after purchase.
WooCommerce
Note: Zonos Catalog bundles are not currently supported on WooCommerce.
WooCommerce stores can still sell bundled products using plugins like
WooCommerce Product Bundles,
but these are not matched to Zonos bundle definitions for component-level
landed cost calculations. Each item in the cart is treated as a standalone
product.
If you sell bundles on WooCommerce today, Zonos calculates landed cost on each
cart item individually. To get per-component HS codes and accurate duty rates,
ensure each component product in your WooCommerce store has the correct
classification data in your Zonos Catalog.
The bundle's SKU in Zonos Catalog must match the Magento product
entity ID (numeric). You can find this in your Magento admin under the
product listing. Magento has a native bundle product type — when a
customer adds a Magento bundle to their cart, the platform sends the parent
product to Zonos as a single line item.
Magento manages inventory on the bundle's child products, not the parent.
When a bundle is ordered, stock is decremented on each component individually.
The bundle parent does not have its own inventory count.
Magento supports virtual and downloadable product types. If your
bundle includes non-physical components, exclude them from the Zonos bundle
definition and only include the physical items. Magento handles delivery of
virtual and downloadable products separately.
Zonos creates shipping labels for the physical components. The Magento order
displays the original bundle line item. Tracking numbers are applied at the
order level, and Magento handles invoice generation for the full bundle
including any non-physical components.
The bundle's product ID in Zonos Catalog must match the Miva product
code (the string identifier from your Miva product catalog). Miva uses a
native variant/kit system — when a customer selects a product variant
that contains multiple parts, Miva sends the kit information to Zonos.
The Miva integration supports multi-carton kit fulfillment. When a bundle
ships in multiple boxes, each carton is matched to its order items and
creates a separate shipment with its own tracking number.
If your bundle includes non-physical items, mark them as non-shippable in
Miva and exclude them from the Zonos bundle definition. Non-shippable items
are passed through to Zonos and excluded from the landed cost calculation.
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 order creation. When a customer buys a bundle, Zonos expands it into its components, scales each component's price so that the total matches the parent bundle price, and calculates duties and taxes based on each individual component.
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 five by giving Zonos the component breakdown, box assignments (or auto-box grouping), and price allocation up front. The result is a landed cost quote, commerical 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.
Platform integrations
Each e-commerce platform handles bundles differently. The sections below describe how Zonos bundles interact with each supported platform.
Shopify
Setup
The bundle's product ID in Zonos Catalog must match the Shopify variant ID of the bundle product. Use the numeric variant ID only (e.g.,
45271622844730), not the full GraphQL ID. 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
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.
Non-shippable items
Shopify items flagged as non-shippable (digital downloads, gift cards, etc.) are automatically excluded from the landed cost calculation. If a bundle contains a mix of physical and digital components, only the physical components are sent to Zonos for rating and fulfillment.
BigCommerce
Setup
The bundle's SKU or product ID in Zonos Catalog must match the BigCommerce product identifier. BigCommerce product IDs are numeric only (e.g.,
12345), so ensure the product ID in your Zonos bundle definition is the numeric BigCommerce product ID. BigCommerce natively separates cart items into physical items and digital items, which affects how bundles with mixed content are handled.Order flow
When a customer orders a bundle on a BigCommerce store:
Digital goods in bundles
BigCommerce supports digital items — for example, a digital editing software download. Because BigCommerce sends access to digital goods upon fulfillment digital goods cannot be included as part of the bundle defintion in Zonos. The best solution is usually to price the physical goods in the bundle as the full price of the bundle and then create A promotional rule in Bigcommerce to include the digital items when ever the bundle is in the cart.
Fulfillment
BigCommerce handles digital item delivery (email/download) separately from physical fulfillment. Physical bundle components are fulfilled through Zonos with shipping labels and tracking. Digital items are delivered by BigCommerce automatically after purchase.
WooCommerce
If you sell bundles on WooCommerce today, Zonos calculates landed cost on each cart item individually. To get per-component HS codes and accurate duty rates, ensure each component product in your WooCommerce store has the correct classification data in your Zonos Catalog.
Magento
Setup
The bundle's SKU in Zonos Catalog must match the Magento product entity ID (numeric). You can find this in your Magento admin under the product listing. Magento has a native bundle product type — when a customer adds a Magento bundle to their cart, the platform sends the parent product to Zonos as a single line item.
Order flow
When a customer orders a bundle on a Magento store:
Inventory
Magento manages inventory on the bundle's child products, not the parent. When a bundle is ordered, stock is decremented on each component individually. The bundle parent does not have its own inventory count.
Virtual and downloadable products
Magento supports virtual and downloadable product types. If your bundle includes non-physical components, exclude them from the Zonos bundle definition and only include the physical items. Magento handles delivery of virtual and downloadable products separately.
Fulfillment
Zonos creates shipping labels for the physical components. The Magento order displays the original bundle line item. Tracking numbers are applied at the order level, and Magento handles invoice generation for the full bundle including any non-physical components.
Miva
Setup
The bundle's product ID in Zonos Catalog must match the Miva product code (the string identifier from your Miva product catalog). Miva uses a native variant/kit system — when a customer selects a product variant that contains multiple parts, Miva sends the kit information to Zonos.
Order flow
When a customer orders a kit on a Miva store:
Multi-carton fulfillment
The Miva integration supports multi-carton kit fulfillment. When a bundle ships in multiple boxes, each carton is matched to its order items and creates a separate shipment with its own tracking number.
Non-shippable items
If your bundle includes non-physical items, mark them as non-shippable in Miva and exclude them from the Zonos bundle definition. Non-shippable items are passed through to Zonos and excluded from the landed cost calculation.
CatalogItemInput PackagingOptionCreateInput
catalogItemCreate catalogItemDelete catalogItemUpdate packagingOptionCreate
Was this page helpful?