DOCS

Bundles

HomeGlobal ecommerce Catalog Bundles

Bundles

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

A bundle 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 bundle, 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 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 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 bundles work 

When you create a bundle in Catalog, you define:

  • Bundle SKU or product ID — the product identifier
  • Bundle price - the total price as it appears in your store.
  • 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 — 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 bundle is placed, Zonos automatically:

  1. Expands the bundle 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 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 Shopify variant ID of the bundle product.
  1. Go to Dashboard → Products → Bundles.
  2. Click Add Bundle in the top right corner.
  3. Enter the bundle 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 bundle 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 bundle
    • Box — which box this component ships in (add multiple boxes if your bundle ships in more than one)
    • Price ratio — the portion of the bundle price this component represents (used to calculate per-component declared values)
  6. Click Save.

To bulk-create bundles by importing a CSV file:

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

Bundle CSV fields

Column↕Description↕
Kit SKUThe SKU of the bundle as it appears in your store.
Kit Product IDThe product ID of the bundle as it appears in your store.
Kit NameThe name of the bundle.
Kit DescriptionA description of the bundle.
Kit Image URLImage URL for the bundle.
Kit AmountThe total price of the bundle.
Kit CurrencyThe currency of the bundle 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 bundle.

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

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

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

To delete multiple bundles at once:

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

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

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

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

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, 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 bundle'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 bundle with 4 tires at equal ratios (0.25 each) declares each tire at $250. If instead the bundle 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 

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 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. Non-bundle items in the same order are packed separately using the standard cartonization algorithm.

Mixed bundle orders 

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

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

Zonos expands each bundle 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 

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:

  1. Shopify sends a single line item for the bundle parent (e.g., "Truck Tire 4-Pack x 1").
  2. Zonos matches the line item's variant ID to the bundle's product ID in your catalog.
  3. 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.
  4. 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

CatalogItemExportJobCreateInput CatalogItemInput PackagingOptionCreateInput

MUTATIONS

catalogItemCreate catalogItemDelete catalogItemExportJobCreate catalogItemUpdate packagingOptionCreate

Book a demo

Was this page helpful?

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