# Zapstra > Zapstra builds operations-grade e-commerce software for Shopify merchants. Zapstra is a software company focused on solving complex operational problems for Shopify stores. Our product lines are organized under four pillars: Flow (order operations), Pulse (analytics), Forge (product tooling), and Edge (storefront performance). Our flagship product is **BundlesIQ** (under the Flow pillar) — an operations-grade Shopify bundle management app. BundlesIQ maps bundle ("ghost SKU") products to their component SKUs so merchants can run bundles with fulfillment accuracy, inventory integrity, and reporting behavior that matches their workflow. **Key capabilities of BundlesIQ:** - **Handling modes** — Four modes (Hybrid, Reporting, Operational, Parent-Only/BOM) that control how bundle orders are represented after processing - **Pricing allocation** — Automatically distributes the bundle price across components using uniform percentage or per-component discount strategies - **3PL support** — Prevents premature warehouse imports by tagging/holding orders until bundle processing completes - **Draft order support** — Processes bundles in draft orders for B2B and wholesale workflows - **Inventory sync** — Derives bundle availability from component stock levels - **Health monitoring** — Dashboard showing processing status, errors, and flags BundlesIQ works exclusively on Shopify and processes orders after they are created. It does not provide a storefront bundle builder or modify carts at checkout. ## Products - [BundlesIQ](https://zapstra.com/solutions/bundlesiq): Operations-grade Shopify bundle management — maps ghost SKU products to component SKUs with flexible handling modes, pricing allocation, and 3PL protection. ## Documentation - [Getting Started](https://zapstra.com/documentation/bundlesiq/getting-started): Introduction to BundlesIQ — what it does, how it works, and key concepts - [Handling Modes](https://zapstra.com/documentation/bundlesiq/handling-modes): Detailed guide to Hybrid, Reporting, Operational, and Parent-Only/BOM modes - [Troubleshooting & FAQ](https://zapstra.com/documentation/bundlesiq/troubleshooting): Common questions, expected behavior by mode, and error diagnosis - [3PL Integration](https://zapstra.com/documentation/bundlesiq/tpl-integration): Setting up BundlesIQ with third-party logistics providers - [Pricing Strategy](https://zapstra.com/documentation/bundlesiq/pricing-strategy): How bundle prices are allocated across component SKUs - [Order Representation](https://zapstra.com/documentation/bundlesiq/order-representation): How orders look after BundlesIQ processes them in each mode - [Inventory Rules](https://zapstra.com/documentation/bundlesiq/inventory-rules): Configuring inventory sync between bundles and components - [Create a Bundle](https://zapstra.com/documentation/bundlesiq/create-a-bundle): Step-by-step guide to creating and managing bundles ## Details - [Full Documentation](https://zapstra.com/llms-full.txt): A comprehensive single-file version of all Zapstra product documentation, optimized for LLM context windows. ## Optional - [About Zapstra](https://zapstra.com/about): Company information and mission - [Join Beta](https://zapstra.com/solutions/bundlesiq): Sign up for early access to BundlesIQ - [Terms of Service](https://zapstra.com/terms): Terms and conditions - [Privacy Policy](https://zapstra.com/privacy): Privacy policy --- - [Sitemap](https://zapstra.com/sitemap.xml) ## Full Documentation: BundlesIQ ### Introduction # Getting Started with BundlesIQ BundlesIQ is an operations-grade Shopify bundle management app that maps bundle ("ghost SKU") products to their component SKUs—so you can run bundles with fulfillment accuracy, inventory integrity, and reporting behavior that matches your workflow. ![BundlesIQ home dashboard in Shopify Admin — health summary, system status, and lifetime statistics](/assets/docs/images/bundlesiq/home-dashboard-nav-expanded.png) ## What BundlesIQ Does BundlesIQ solves the core bundle problem on Shopify: when a customer purchases a bundle (a “ghost SKU” product), BundlesIQ maps that purchase to the underlying component SKUs. In order-editing modes, it expands the bundle into component line items on the order; in Parent-Only/BOM mode, it leaves the order intact while managing component inventory behind the scenes. This helps your team pick the right items and keeps inventory aligned—while letting you choose whether reporting follows the bundle, the components, or both. **BundlesIQ handles:** - **Bundle definition and management** — Link a ghost SKU product to component products and quantities - **Automatic order transformation** — Detect bundle orders (and draft orders) and process them according to your selected handling mode - **Flexible handling modes** — Choose how the order is represented after processing: - **Hybrid**: keep the bundle as a $0 reference + add components - **Reporting**: keep the bundle at full price + add components - **Operational**: remove the bundle + keep only components - **Parent-Only/BOM**: skip order editing and manage component inventory behind the scenes - **Pricing allocation** — Automatically distribute the bundle price across components using uniform percentage or per-component discount strategies - **Optional inventory sync** — Derive bundle availability from component stock so bundles can reflect component constraints - **3PL protection** — Help prevent premature warehouse imports by tagging/holding orders until bundle processing completes - **Draft order support** — Process bundles in draft orders for B2B and wholesale workflows - **Health monitoring** — Dashboard showing processing status, errors, and flags for orders that need attention > Note: BundlesIQ is intentionally flexible. Your mode + inventory settings determine whether Shopify “reports like a bundle,” “reports like components,” or “supports both,” and the tradeoffs are documented in Handling Modes and Order Representation. ## What BundlesIQ Does Not Do - **Storefront bundle builder** — BundlesIQ does not provide a customer-facing “build your own bundle” page or widget. It focuses on the operational side of bundles - **Checkout-time modification** — BundlesIQ does not change carts at checkout. It processes orders after they are created (and can also process draft orders) - **Multi-platform support** — BundlesIQ currently works with Shopify only - **Subscription billing** — BundlesIQ does not manage subscription billing. It can process subscription-generated orders when they appear as standard Shopify orders and allow post-order edits - **Full inventory management** — BundlesIQ can derive bundle availability from components, but it does not replace your inventory management system - **POS-specific UI** — BundlesIQ does not provide POS-specific UI or workflows. It can process POS orders when they flow into Shopify as editable orders ## How It Works (High Level) 1. You **create a bundle** in BundlesIQ by selecting a Shopify product (the ghost SKU) and adding the component products that make up the bundle 2. You **configure your handling mode** to control how orders should be represented after processing 3. You **set your pricing strategy** to determine how the bundle price is allocated across components 4. When a customer **places an order** containing a bundle product, BundlesIQ automatically detects it via webhook 5. BundlesIQ **processes the order based on your mode**: - In order-editing modes: add component line items, allocate pricing/discounts, and optionally remove or zero out the bundle line - In Parent-Only/BOM: leave the order unchanged and manage component inventory behind the scenes 6. Your team **fulfills the correct items**—either from the component lines on the order (order-editing modes) or from the bundle definition/BOM (Parent-Only/BOM) 7. Your **reporting reflects the representation you chose** (bundle, components, or both), based on your handling and inventory configuration ## Next Steps - [Install BundlesIQ](/documentation/bundlesiq/installation) and grant the required permissions - [Create your first bundle and place a test order](/documentation/bundlesiq/quickstart) - [Understand core concepts](/documentation/bundlesiq/glossary) like ghost SKUs, handling modes, and pricing strategies --- ### Installation # Installation and Permissions BundlesIQ installs through the Shopify App Store using standard OAuth authentication. This page explains what access the app requires and why. ## Install BundlesIQ 1. **Visit** the BundlesIQ listing on the Shopify App Store 2. **Click** **Add app** and confirm installation on your Shopify store 3. **Review** the requested permissions and approve them 4. **Complete** the onboarding wizard to select your default handling mode and configure basic settings ![BundlesIQ onboarding wizard — select your default handling mode with a live Order Preview](/assets/docs/images/bundlesiq/onboarding-screen.png) ## Required Permissions BundlesIQ requests the following Shopify access scopes during installation: ### Products | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_products` | Look up bundle and component product/variant data (prices, SKUs, status, images) for detection, pricing calculation, and the product search modal | | `write_products` | Sync derived bundle inventory levels and retail prices back to the ghost SKU product when inventory sync or retail sync is enabled | ### Orders | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_orders` | Detect bundles on incoming orders, read line items, tags, discount allocations, and metafields for processing and the Health dashboard | | `write_orders` | Write processing tags (`BIQ_PROCESSING`, `BIQ_READY`, `BIQ_ERROR`), write transformation audit metafields, and update order note attributes | | `write_order_edits` | Transform orders via the Order Edit API — add component line items, apply discounts, and modify or remove the bundle line item | ### Draft Orders | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_draft_orders` | Detect bundles on draft orders and read line item data for B2B and wholesale processing | | `write_draft_orders` | Transform draft orders by replacing line items via the `draftOrderUpdate` mutation. Also used for reverting draft order transformations | ### Inventory | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_inventory` | Calculate bundle availability from component stock levels across locations | | `write_inventory` | Sync derived bundle inventory back to the ghost SKU variant. In Parent-Only (BOM) mode, also used to reserve, consume, and release component inventory via Shopify's inventory state API | ### Fulfillment | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_fulfillments` | Read fulfillment order status to determine hold eligibility and check fulfillment state during processing | | `write_assigned_fulfillment_orders` | Place and release fulfillment holds on orders assigned to your locations (3PL protection) | | `write_merchant_managed_fulfillment_orders` | Place and release fulfillment holds on merchant-managed fulfillment orders (3PL protection) | | `write_third_party_fulfillment_orders` | Place and release fulfillment holds on third-party fulfillment orders (3PL protection) | ### Discounts, Locations, and Other Data | Scope | Why BundlesIQ Needs It | |-------|----------------------| | `read_discounts` | Read discount code and automatic discount information from orders to factor promo discounts into component price allocation | | `read_locations` | Read Shopify location data for multi-location inventory sync and Parent-Only (BOM) location strategy configuration | | `read_markets` | Read market and currency configuration for multi-currency pricing support | | `read_locales` | Read store locale settings for localized content | | `read_metaobjects` | Read metaobject definitions used by the storefront extension for "What's Included" display | | `read_returns` | Read return data to track component restocking behavior for bundle orders | ## Webhooks Registered BundlesIQ subscribes to Shopify webhooks to respond to store events in real time. The key webhook groups are described below. ### Core Processing These webhooks drive bundle detection and order transformation: | Webhook | Purpose | |---------|---------| | `orders/create` | Detect new orders containing bundle products and begin processing | | `orders/updated` | Detect order changes and support reprocessing workflows | | `orders/paid` | Trigger processing for payment-gated workflows. Also used by Parent-Only (BOM) mode when reserve timing is set to `orders/paid` | | `orders/cancelled` | Release reserved component inventory (Parent-Only mode) and update processing state | | `draft_orders/create` | Detect new draft orders containing bundle products | | `draft_orders/update` | Process draft orders when they are created or modified | | `draft_orders/delete` | Clean up processing state when a draft order is deleted | ### Inventory and Catalog Sync These webhooks keep bundle availability, pricing, and configuration in sync with your Shopify catalog: | Webhook | Purpose | |---------|---------| | `inventory_levels/update` | Recalculate bundle availability when component stock changes at any location | | `inventory_levels/connect` / `disconnect` | Track when inventory is enabled or disabled at a location, affecting bundle availability calculations | | `inventory_items/create` / `update` / `delete` | Track changes to inventory item settings (e.g., tracking status, cost) for components and ghost SKUs | | `products/create` / `update` / `delete` | Detect when component or ghost SKU products are created, modified, or removed. Used for retail price sync, status checks, and bundle validation | | `collections/create` / `update` / `delete` | Track collection changes that may affect bundle product visibility | ### Fulfillment and Order Lifecycle BundlesIQ monitors fulfillment events to manage 3PL protection holds, track order state for the Health dashboard, and handle inventory consumption in Parent-Only (BOM) mode: | Webhook | Purpose | |---------|---------| | `orders/fulfilled` / `orders/partially_fulfilled` | Track fulfillment progress. In Parent-Only mode, triggers consumption of reserved component inventory | | `orders/edited` | Detect external edits to orders that were already processed by BundlesIQ | | `orders/delete` | Clean up processing state when an order is deleted | | `refunds/create` | Detect refunds on bundle orders to update the Health dashboard and, in Parent-Only mode, restock reserved or consumed component inventory | | `fulfillment_orders/*` | A set of fulfillment order webhooks (moved, merged, split, hold released, routing complete, and others) used to manage Shopify-native fulfillment holds for 3PL protection | | `fulfillments/create` / `update` | Track fulfillment creation and updates for processing state and inventory lifecycle management | | `fulfillment_events/create` | Track fulfillment milestone events (e.g., shipped, delivered) | ### Discounts, Markets, and Locations | Webhook | Purpose | |---------|---------| | `discounts/create` / `update` / `delete` | Track discount changes that may interact with bundle pricing allocation | | `markets/create` / `update` / `delete` | Track market configuration changes for multi-currency pricing support | | `locations/create` / `update` / `delete` | Track location changes for multi-location inventory sync and Parent-Only location strategy | | `selling_plan_groups/create` / `update` / `delete` | Track subscription selling plan changes for compatibility with subscription app orders | ### App Lifecycle BundlesIQ subscribes to app lifecycle and billing webhooks for operational purposes: | Webhook | Purpose | |---------|---------| | `app/uninstalled` | Clean up app data, release fulfillment holds, and revoke access when the app is removed | | `app_subscriptions/update` | Track billing plan changes and usage updates | | `app_subscriptions/approaching_capped_amount` | Trigger notifications when Scale+ overage usage approaches the spending cap | | `app/scopes_update` | Detect changes to granted access scopes | | `shop/update` | Track store configuration changes (currency, timezone, plan) | ## Data Storage BundlesIQ stores the following data: - **Bundle definitions** — Bundle name, status, ghost SKU reference, component list, pricing configuration, and constraints - **Processing logs** — Timestamped records of every order transformation, including success/failure status, flags, and pricing details - **Bundle instances** — Per-order snapshot of which bundles were detected, how they were transformed, and the resulting line item mapping - **Store settings** — Your handling mode preference, processing scope, 3PL protection configuration, and sync settings All data is stored securely in BundlesIQ's cloud infrastructure. Bundle metadata is also written to Shopify order metafields for auditability. ## Firewall and Network Requirements BundlesIQ operates as a cloud-hosted service. No firewall configuration is required on your end. Webhook delivery uses Shopify's standard webhook infrastructure. ## Next Steps - [Create your first bundle and place a test order](/documentation/bundlesiq/quickstart) - [Configure your global settings](/documentation/bundlesiq/global-settings) --- ### Quickstart # Quickstart: Create Your First Bundle Follow this guide to create your first bundle in BundlesIQ, run the built-in test, and verify that order transformation works correctly. ## Terminology BundlesIQ maps **Shopify variants to variants**. - A **product** can have one or more **variants** - A **ghost SKU** in BundlesIQ is the **bundle’s purchasable variant** (the variant customers add to cart) - **Components** are the **variant(s)** included inside the bundle (with quantities) > In other words: BundlesIQ operates at the SKU-level (variants), even if Shopify Admin UI often talks in “products”. ## Before You Begin - BundlesIQ is [installed](/documentation/bundlesiq/installation) on your Shopify store - You completed onboarding and selected a default [handling mode](/documentation/bundlesiq/handling-modes) - Your **component variants** already exist in Shopify (BundlesIQ can create the bundle item, but **components must already exist**) - You either: - already have a Shopify product/variant you want to use as the **ghost SKU**, **or** - you’ll create the ghost SKU variant directly inside BundlesIQ during bundle creation (recommended for speed) --- ## Step 1 (Optional): Prepare Your Ghost SKU Variant in Shopify You can skip this step if you plan to click **Create New Item** inside BundlesIQ. If you already have a Shopify product/variant you want to use as the ghost SKU: 1. **Open** the bundle product in Shopify Admin 2. **SKU is optional:** BundlesIQ identifies items by **variant ID**, not SKU - You *can* still set a SKU for your own reporting/workflows 3. **Inventory tracking (important):** - If you want Shopify to prevent overselling: - Turn **Track quantity** **ON** for the ghost SKU variant - Turn **Continue selling when out of stock** **OFF** - If you enable **Sync Bundle Inventory** in BundlesIQ, the ghost SKU variant must have **inventory tracking ON** (BundlesIQ updates available quantity based on components). 4. **Shipping (optional):** - Many stores set the ghost SKU to **not** require shipping since the physical items are the components. - Some stores keep shipping **ON** if they rely on the ghost SKU variant for checkout shipping calculations. Choose what matches your workflow. --- ## Step 2: Create the Bundle in BundlesIQ 1. **Navigate** to **BundlesIQ > Bundles** in your Shopify Admin sidebar 2. **Click** **Create Bundle** (top-right) ### 2A) Info & Configuration Card 1. **Give the bundle a name** - Internal reference only (recommended: match or closely resemble the ghost SKU item name) 2. **(Optional) Pricing Mode** - Defaults to your shop’s default (collapsed section; can be overridden per bundle) 3. **(Optional) Handling Mode** - Defaults to your shop’s default (collapsed section; can be overridden per bundle) ### 2B) Bundle Components Card #### 1) Select or create the Ghost SKU item - Click **Select Product From Shopify** to choose an existing Shopify item, **or** - Click **Create New Item** to create the bundle item from inside BundlesIQ (fastest path) > Note: Creating the ghost SKU item in BundlesIQ is more limited than Shopify Admin. Components cannot be created here—components must already exist in Shopify. #### 2) Add components - Click **Add Components** to search and add component variants, **or** - Click **Import CSV** to bulk add components + quantities **If importing CSV:** 1. Download the template 2. In the `identifier` column, paste one of: - SKU, barcode, variant ID, or Shopify GID 3. In the `quantity` column, enter the per-bundle component quantity - Quantity defaults to **1** if omitted #### 3) Configure pricing details (depends on Pricing Mode / Handling Mode) **If Pricing Mode = Bundle-Led:** - Set the **ghost SKU variant’s retail price** (this is the bundle price customers pay) - Ensure the **sum of component retails × quantities** is **>=** the bundle price - Why: Shopify does not allow increasing a component’s line item price above the variant’s price, so the allocation must fit within component retails. **If Pricing Mode = Component-Led:** - For each component you can configure pricing such as: - No Discount - Percent Off - Amount Off - Fixed Price - **Fixed Price constraint:** fixed price must be **<=** the component’s retail price. **If Handling Mode = Parent-Only (BOM):** - This workflow is cost-driven and behaves differently than Operational/Hybrid/Reporting. - In this mode you’ll typically see: 1. The bundle price (ghost SKU) is expected to be **>=** total component cost 2. An **Add Cost** button for labor/overhead/non-consumables 3. Cost / profit / margin % summaries at the bottom ### 2C) Advanced Settings Card Depending on the handling mode and the ghost SKU’s inventory configuration, you may see options such as: - **Sync Bundle Inventory** - **Sync Bundle Retail** > Reminder: **Sync Bundle Inventory requires the ghost SKU variant to track inventory** in Shopify. ### 2D) Save & Activate 1. Set status to **Active** (if not already) 2. **Click Save** BundlesIQ is now watching for orders/draft orders containing this bundle’s ghost SKU variant (based on your processing settings). --- ## Step 3: Run the Built-In Test Instead of manually placing a test order, use the **Test Bundle** button at the top of the bundle page (after saving and activating). This runs a suite of checks to catch issues early. ### What “Test Bundle” does (high-level) 1. Creates a **draft order** (validates webhooks + processing pipeline) 2. Verifies the draft order was transformed correctly for the bundle’s configuration 3. Verifies bundle metadata/metafields were written as expected 4. Deletes the draft order (keeps your store clean) > You may briefly see the draft order appear in Shopify Admin before it’s deleted. --- ## Step 4: Verify the Transformation in Shopify Admin (Recommended) The test covers most validation, but it’s still smart to sanity-check one or two real scenarios in Shopify Admin. 1. Open an order/draft order in Shopify Admin 2. Confirm line items match your handling mode: **Hybrid** - Ghost SKU remains at **$0.00** - Component line items appear with allocated prices - Order total matches the original bundle price **Operational** - Ghost SKU is removed (quantity set to 0 / removed) - Only component line items remain with allocated prices - Order total matches the original bundle price **Reporting** - Ghost SKU remains at its original price - Component line items appear at **$0.00** - Order total matches the original bundle price **Parent-Only (BOM)** - Ghost SKU remains at its original price - No component line items appear - Order total matches the bundle price 3. Check the BundlesIQ **Health** dashboard to confirm processing completed without errors --- ## Step 5: Verify Inventory (Optional) Inventory behavior has two different layers: 1. **Component inventory (Shopify-native behavior):** When components are on the order (Operational/Hybrid/Reporting), Shopify updates inventory through its normal reservation/fulfillment flow. In early tests, this can be hard to validate without real inventory implications. 2. **Ghost SKU inventory (BundlesIQ sync option):** If **Sync Bundle Inventory** is enabled, BundlesIQ keeps the ghost SKU’s available quantity aligned to component availability (requires inventory tracking enabled on the ghost SKU variant). --- ## Common Issues - **Order was not transformed** - Confirm the bundle status is **Active** - Confirm your processing scope includes the order type (orders, draft orders, or both) - Confirm BundlesIQ webhooks are registered and enabled (Settings) - Confirm the ghost SKU and component variants are **active** (not archived / not draft) - **Prices don’t look right** - Re-check Pricing Mode configuration and constraints (especially fixed price rules and bundle-led allocation limits). See [Pricing Strategy](/documentation/bundlesiq/pricing-strategy) - **Ghost SKU still shows on the order** - Expected in **Hybrid** (at $0), **Reporting** (at full price), and **Parent-Only** (at full price, no components) - Only **Operational** mode removes it entirely --- ## Next Steps - [Understand handling modes in depth](/documentation/bundlesiq/handling-modes) - [Configure your pricing strategy](/documentation/bundlesiq/pricing-strategy) - [Set up 3PL protection](/documentation/bundlesiq/tpl-integration) - [Run the full go-live checklist](/documentation/bundlesiq/go-live-checklist) --- ### Glossary # Glossary This page defines the key terms and concepts used throughout BundlesIQ. Refer to this glossary when you encounter unfamiliar terminology in the app or documentation. ## Bundle Terms - **Bundle** — A product that is composed of multiple individual items (components) sold as a single unit. In BundlesIQ, a bundle links a ghost SKU to its component variants - **Ghost SKU** — The Shopify product variant that represents the bundle in your store. Customers purchase this SKU, but it does not correspond to a physical item in your warehouse. BundlesIQ "explodes" it into real component SKUs on the order - **Component** — An individual product variant that is part of a bundle. Components are the real, physical items that get picked, packed, and shipped - **Bundle explosion** — The process of transforming a bundle line item on an order into its individual component line items. Also called "order transformation" - **Bundle instance** — A record of a specific bundle occurrence on a specific order. Each time a bundle is detected and processed on an order, BundlesIQ creates a bundle instance with a snapshot of the configuration used ## Handling Modes - **Handling mode** — The setting that controls how BundlesIQ visually transforms an order after detecting a bundle. There are four modes - **Hybrid mode** — The bundle line item remains on the order at $0.00 as a reference label. Component line items are added with their allocated prices. Best for B2B and wholesale where you want to show both the bundle identity and individual component pricing - **Reporting mode** — The bundle line item stays on the order at its original purchase price. Component line items are added at $0.00 for fulfillment visibility. Best for DTC stores where revenue should attribute to the bundle SKU - **Operational mode** — The bundle line item is fully removed from the order (quantity set to 0). Only priced component line items remain. Best for warehouses, distributors, and 3PL-driven workflows that require strict SKU-level accuracy - **Parent-Only (BOM) mode** — The bundle line item stays on the order at its original price and no component line items are added. Component inventory is reserved, consumed, and restocked behind the scenes using Shopify inventory states. Best for made-to-order, kitting, and assembly workflows. Currently in Beta ## Pricing Terms - **Pricing strategy** — The setting that determines how the bundle price relates to component prices. Independent of handling mode - **Bundle-led pricing** — The bundle's retail price is the fixed, pinned value. Component prices are calculated by distributing the bundle price across components - **Component-led pricing** — Each component's bundle price is set individually (via percentage, dollar, or specific price discounts). The bundle's retail price is derived as the sum of component bundle prices - **Uniform percent** — A discount strategy where the same percentage discount is applied to every component in the bundle - **Proportional allocation** — A discount strategy where the bundle price is distributed across components proportionally based on their retail values - **Per-component discount** — A discount strategy where each component can have a different discount type and amount (percentage off, dollar off, or specific retail price) - **Price allocation** — The process of distributing the bundle's total price across its component line items during order transformation ## Inventory Terms - **Bundle availability** — The maximum number of bundles that can be sold, derived from component stock levels. Calculated as the minimum of (component available quantity / quantity per bundle) across all components - **Inventory sync** — The automatic process of updating the ghost SKU's inventory level in Shopify based on the current bundle availability calculated from components - **Computed availability** — The derived bundle stock level based on the "least available component" logic - **Reserved inventory** — In Parent-Only (BOM) mode, component stock that has been allocated to an order but not yet consumed. Uses Shopify's `reserved` inventory state to move units from `available` to `reserved` without adding component line items to the order ## Order Processing Terms - **Order transformation** — The complete process of detecting a bundle on an order, calculating prices, adding component line items, and committing the changes to Shopify - **Draft order processing** — Bundle transformation applied to Shopify draft orders, commonly used in B2B and wholesale workflows - **Processing scope** — The global setting that controls which orders BundlesIQ processes (all orders, tagged orders only, or orders with specific exclusion tags) - **Idempotent processing** — BundlesIQ marks processed orders with metadata to prevent duplicate transformations if the same webhook fires more than once - **Reprocessing** — The act of re-running the full bundle transformation pipeline for an order. Clears existing instances, strips BIQ tags, and processes the order from scratch. Available from the Bundle Tools admin action on orders and draft orders - **Reverting** — The act of undoing a bundle transformation on a draft order, restoring it to its pre-BundlesIQ state by removing component lines and restoring original bundle lines. Only available for draft orders ## 3PL and Fulfillment Terms - **3PL protection** — A set of tag-based and hold-based mechanisms that prevent fulfillment partners from importing or acting on orders before bundle processing completes - **BIQ_PROCESSING tag** — Applied to orders when BundlesIQ begins processing. Used as a signal to 3PLs to skip the order - **BIQ_READY tag** — Applied to orders after BundlesIQ successfully completes processing. Used as the allowlist signal for 3PLs to import the order - **BIQ_ERROR tag** — Applied to orders when BundlesIQ processing fails. The order remains blocked from fulfillment until the issue is resolved - **BIQ_REVERTED tag** — Applied to draft orders when a bundle transformation is reverted (undone). Prevents the webhook-worker from automatically re-transforming the draft order when Shopify fires the `draft_orders/update` webhook in response to the revert - **Fulfillment hold** — A Shopify-native mechanism that places the order's fulfillment orders in an "On hold" state, preventing fulfillment until the hold is released ## Configuration Terms - **Variance absorber** — An automatic reconciliation mechanism that corrects small rounding differences (typically a few cents) between the expected and calculated order totals after transformation - **Writer options** — Advanced settings that control how BundlesIQ writes line items to Shopify, including merge behavior, grouping headers, and safety limits - **BOM cost lines** — Optional cost entries (e.g., Labor, Overhead, Packaging) that can be attached to a bundle in Parent-Only (BOM) mode for internal cost tracking. These are not visible on the Shopify order - **Reserve timing** — A Parent-Only setting that controls when component inventory is reserved: either when the order is created (`orders/create`) or when the order is paid (`orders/paid`) - **Location strategy** — A Parent-Only setting that determines which Shopify location is used for inventory reservations: the fulfillment order's assigned location or a single fixed location ## Related Pages - [How BundlesIQ Works](/documentation/bundlesiq/how-bundlesiq-works) - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) --- ### How It Works # How BundlesIQ Works BundlesIQ expands **bundle variants** into their **component variants** (depending on your configured handling mode) so your storefront can sell a single “bundle item” while your operations and reporting reflect the underlying items. ![BundlesIQ home dashboard showing health summary, active bundles, and system status](/assets/docs/images/bundlesiq/biq-home-dashboard.png) --- ## Terminology (important) BundlesIQ works **variant-to-variant**: - **Product**: A Shopify product container (what merchants often navigate in Admin) - **Variant**: The purchasable SKU-level item (this is what BundlesIQ maps and detects) - **Ghost SKU variant**: The *bundle* variant customers buy (the “parent” line item) - **Component variants**: The variant(s) contained in the bundle, each with a quantity > When this document says “product,” it’s referring to how Shopify Admin is organized. The actual detection and mapping is always done using **variant IDs**. --- ## The Ghost SKU Model BundlesIQ uses a **ghost SKU variant** approach to bundling: 1. You choose the variant customers will purchase as the bundle: - **Select an existing Shopify variant**, or - **Create the bundle item inside BundlesIQ** (faster, but more limited than Shopify Admin) 2. In BundlesIQ, you define the bundle by linking that ghost SKU variant to one or more **component variants** (plus quantities) 3. When a customer purchases the ghost SKU variant, BundlesIQ detects it and processes the order based on your handling mode (Operational, Hybrid, Reporting, or Parent-Only/BOM) ![Bundle editor showing ghost SKU product, components, quantities, and pricing configuration](/assets/docs/images/bundlesiq/create-bundle-screen.png) ### Concrete example (variant-to-variant) **Product A:** “Apple” - Variant A (standard): “Single” - Variant B (bundle): “Two-Pack” → components: Variant A × 2 - Variant C (bundle): “Three-Pack” → components: Variant A × 3 - Variant D (bundle): “Four-Pack” → components: Variant A × 4 - Variant E (bundle): “Five-Pack” → components: Variant A × 5 > The bundle *looks* like a “product” in Shopify Admin, but BundlesIQ is mapping and processing these as **variants**. --- ## Why Ghost SKU Variants Ghost SKU variants keep the storefront simple while letting the back-office stay precise: - **Customers** see one item with one price - **Ops/Warehouse** can work with the actual pick/pack items (when your mode adds components to the order) - **Accounting/Reporting** can track revenue at the level you choose (bundle-level, component-level, or both) - **Inventory control** depends on handling mode: - In modes where components are on the order, Shopify’s normal inventory flow applies to **component variants** - In Parent-Only (BOM) mode, BundlesIQ can optionally manage component inventory via inventory states (more below) --- ## Handling Modes (What Changes on the Order) BundlesIQ supports multiple handling modes. The mode determines what appears on the final order: | Handling Mode | Ghost SKU variant on order? | Component variants on order? | Typical use case | |---|---:|---:|---| | **Operational** | ❌ Removed | ✅ Yes (priced) | Warehousing + operational reality (pick/pack) | | **Hybrid** | ✅ Yes (set to $0.00) | ✅ Yes (priced) | Ops + bundle visibility retained | | **Reporting** | ✅ Yes (priced) | ✅ Yes (set to $0.00) | Revenue stays on bundle, ops still sees components | | **Parent-Only (BOM)** | ✅ Yes (priced) | ❌ No | Manufacturing/kitting cost model; no order line expansion | ![Order before and after transformation — Hybrid mode showing bundle zeroed and components added](/assets/docs/images/bundlesiq/health-dashboard-handling-mode-hybrid.png) --- ## The Transformation Pipeline When an order (or draft order) is created, BundlesIQ runs this pipeline: ### 1) Detection Shopify sends a webhook (for example, `orders/create` or `draft_orders/create`). BundlesIQ checks each line item’s **variant ID** against its bundle index. - **SKUs are optional** — BundlesIQ does not require SKU to detect bundles - Detection is based on variant identity, not product title/handle ![Processing timeline showing webhook received, bundles detected, pricing calculated, and completed](/assets/docs/images/bundlesiq/health-dashboard-processing-timeline.png) ### 2) 3PL Gating (Optional) If 3PL protection is enabled, BundlesIQ can: - Tag the order as **processing** (example: `BIQ_PROCESSING`) - Optionally place a **fulfillment hold** so your 3PL/warehouse doesn’t import the order prematurely ### 3) Configuration Loading BundlesIQ loads: - Bundle definition (ghost SKU variant + component variants + quantities) - Pricing configuration (bundle-level override or shop defaults) - Handling mode (bundle override or shop default) - Any guardrails (limits, validation rules, 3PL settings, etc.) ### 4) Price Calculation & Validation BundlesIQ determines how pricing should be represented on the order. This is where most edge cases live. Key reality: - BundlesIQ primarily uses **discounts/allocations** to achieve target component prices. - Increasing a component’s effective price above the variant’s base price is not reliably supported in every scenario. Common validations: - **Bundle-Led** pricing typically requires the component retail sum (qty × price) to be **>=** bundle price to avoid impossible allocations - **Fixed Price** on a component must be **<=** the component’s retail price ### 5) Order Transformation (Mode-Dependent) **For Operational / Hybrid / Reporting modes**, BundlesIQ edits the order: - Adds component line items (correct quantities) - Applies discounts/allocations to achieve the configured pricing outcome - Modifies the ghost SKU line depending on handling mode (remove it, set it to $0, or keep it priced) Notes: - BundlesIQ avoids introducing additional charges during transformation (for example, customers shouldn’t suddenly pay *more* because of the expansion). - Final shipping/tax presentation depends on store configuration and Shopify’s calculation rules, but the intent is “no surprise increase due to the transformation itself.” **For Parent-Only (BOM) mode**, BundlesIQ does **not** add component line items to the order: - The ghost SKU line item stays as-is - No component lines appear on the order - BundlesIQ can optionally manage component inventory by transitioning quantities into a non-sellable inventory state (e.g., reserved/committed depending on workflow), then: - consume on fulfillment, or - release on cancellation ### 6) Post-Processing After successful processing: - Processing tag is updated (example: `BIQ_PROCESSING` → `BIQ_READY`) - Holds are released (if enabled) - An audit metafield is written to the order (high-level summary of what happened) - A bundle instance record is saved (full before/after snapshot + internal logs) ### 7) Error Handling If processing fails: - BundlesIQ does not “half-commit” changes. It validates first and only commits the order edit once checks pass. - The order is marked as failed (example: `BIQ_ERROR`) - Details are logged in the BundlesIQ Health dashboard - Optional retry behavior may re-attempt processing after a cooldown - You can manually **Reprocess** an order from Shopify Admin via the BundlesIQ action/menu (re-runs the pipeline) ![Health dashboard processing logs showing order history, modes, outcomes, and durations](/assets/docs/images/bundlesiq/health-dash-processing-logs.png) --- ## Where Data Is Stored BundlesIQ stores data both in Shopify and in BundlesIQ’s cloud database. ### On your Shopify store | Location | Data | |---|---| | Order tags | Processing state tags (e.g., `BIQ_PROCESSING`, `BIQ_READY`, `BIQ_ERROR`) | | Order metafields | Audit trail / transformation summary (e.g., `bundles_iq.transformation_audit`) | | Order notes (optional) | Human-readable warnings/flags (if enabled) | ### In BundlesIQ’s cloud database | Collection | Data | |---|---| | Bundles | Bundle definitions, components, substitution groups, pricing configuration | | Bundle instances | Per-order processing records with before/after snapshots | | Processing logs | Timestamped event log for webhooks, detection, edits, retries | | Settings | Store preferences, handling mode defaults, scope, 3PL config | | Bundle variant index | Ghost SKU variant IDs → bundle definition mapping | | Component bundle index | Component variant IDs → bundles that include them | --- ## Processing Times (What to Expect) BundlesIQ processes asynchronously after Shopify sends the webhook. Processing time depends on: - number of bundles on the order - number of components per bundle - Shopify API throughput + rate limits - whether pricing allocation requires extra validation calls Typical ranges: - Small order (single bundle, few components): **a few seconds** - Multiple bundles / many components: **several seconds to ~tens of seconds** - High-volume queuing: **longer** If 3PL protection is enabled, the order stays held until BundlesIQ marks it ready, so timing variance should not impact fulfillment accuracy. --- ## Related Pages - [Glossary](/documentation/bundlesiq/glossary) - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Pricing Strategy](/documentation/bundlesiq/pricing-strategy) - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) --- ### Global Settings # Global Settings Overview BundlesIQ provides store-level settings that control how bundles are processed across your entire shop. Individual bundles can override some of these settings. ## Accessing Settings 1. **Navigate** to **BundlesIQ > Settings** in your Shopify Admin sidebar 2. **Review** and **configure** each section below 3. **Click** **Save** to apply your changes ## Settings Reference ### Default Handling Mode | Setting | Description | Default | |---------|-------------|---------| | `default_handling_mode` | Controls how orders are visually transformed when a bundle is detected | `"hybrid"` | Options: | Value | Label | Behavior | |-------|-------|----------| | `"hybrid"` | **Hybrid** | Bundle line stays at $0; components added with prices | | `"reporting"` | **Reporting** | Bundle line stays at full price; components added at $0 | | `"operational"` | **Operational** | Bundle line removed; only priced components remain | | `"parent_only"` | **Parent-Only (BOM) — Beta** | Bundle line stays at full price; no component lines added; component inventory is reserved behind the scenes | Individual bundles can override this setting. See [Handling Modes Explained](/documentation/bundlesiq/handling-modes) for a detailed comparison. ### Processing Scope | Setting | Description | Default | |---------|-------------|---------| | `processing_scope.mode` | Whether to process all orders or only orders matching specific tags | `"all"` | | `processing_scope.include_tags` | Tags that qualify an order for processing (when mode is `"tagged_only"`) | Empty | | `processing_scope.exclude_tags` | Tags that should always skip processing, regardless of mode | Empty | **Processing scope mode options:** | Value | Label | Behavior | |-------|-------|----------| | `"all"` | **All** | Process every order | | `"tagged_only"` | **Tagged only** | Process only orders matching the include tags | Use tagged-only processing if you want BundlesIQ to process only wholesale or B2B orders. Add a tag like `wholesale` to the include list, and only orders with that tag will be transformed. ### Order Types | Setting | Description | Default | |---------|-------------|---------| | `process_orders` | Process standard Shopify orders | `true` | | `process_draft_orders` | Process Shopify draft orders | `true` | Enable both if you handle B2B workflows through draft orders and standard DTC orders through the online store. ### Sync Settings | Setting | Description | Default | |---------|-------------|---------| | `sync_bundle_inventory` | Automatically update the ghost SKU's inventory based on component stock levels | `false` | | `sync_bundle_retail` | Automatically update the ghost SKU's retail price when component prices change (component-led pricing only) | `true` | These are store-level defaults. Each bundle can override these settings individually. ### 3PL Protection | Setting | Description | Default | |---------|-------------|---------| | `tpl_protection.enabled` | Master toggle for 3PL protection features | `true` | | `tpl_protection.processing_tag` | Tag applied while BundlesIQ is processing an order | `"BIQ_PROCESSING"` | | `tpl_protection.ready_tag` | Tag applied after successful processing | `"BIQ_READY"` | | `tpl_protection.error_tag` | Tag applied when processing fails | `"BIQ_ERROR"` | | `tpl_protection.use_hold_alias` | Also apply a merchant-configurable hold alias tag | `false` | | `tpl_protection.hold_alias_tag` | Custom hold tag name for 3PL compatibility | `"ON-HOLD"` | | `tpl_protection.use_ready_alias` | Also apply a merchant-configurable ready alias tag | `false` | | `tpl_protection.ready_alias_tag` | Custom ready tag name for 3PL compatibility | `"READY_TO_SHIP"` | | `tpl_protection.use_fulfillment_holds` | Place Shopify-native fulfillment holds during processing | `true` | See [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) for detailed setup instructions. ### Writer Options | Setting | Description | Default | |---------|-------------|---------| | `line_merge_mode` | How to handle duplicate component variants across multiple bundles on the same order | `"merge"` | | `group_bundle_lines` | Visually group component lines under their bundle | `false` | | `add_bundle_headers` | Add header lines to identify bundle groups on the order | `false` | | `bundle_header_template` | Template string for the header line (supports `{bundle_title}` placeholder) | `"Bundle: {bundle_title}"` | | `max_added_lines` | Safety limit on the maximum number of line items BundlesIQ can add to a single order | `499` | | `enable_variance_absorber` | Automatically correct small rounding differences (a few cents) during price allocation | `true` | | `variance_absorber_max_cents` | Maximum total variance (in cents) the absorber will correct per order | `30` | | `variance_absorber_max_cents_per_line` | Maximum variance (in cents) the absorber will apply to any single line item | `10` | **Line merge mode options:** | Value | Label | Behavior | |-------|-------|----------| | `"merge"` | **Merge** (default) | When multiple bundles on the same order share the same component variant, quantities and discounts are merged into a single line item. Uses a weighted average discount calculation | | `"isolate"` | **Isolate** | Each bundle's components stay as separate line items, even if they share variants. This keeps each bundle's components visually distinct on the order | | `"duplicates"` | **Duplicates** | Allows duplicate variant lines on the order (uses `allowDuplicates: true` in the Order Edit API). Use this when you need each bundle instance to have its own independent line items | ### Retry Settings | Setting | Description | Default | |---------|-------------|---------| | `retry_settings.enabled` | Automatically retry failed bundle processing | `true` | | `retry_settings.max_attempts` | Maximum number of retry attempts after initial failure | `1` | | `retry_settings.cooldown_minutes` | Minimum time between retry attempts | `5` | ### Error Handling | Setting | Description | Default | |---------|-------------|---------| | `error_handling.append_to_notes` | Write error summaries to Shopify order note attributes | `false` | | `error_handling.include_warnings` | Include warnings (not just errors) in order notes | `false` | ### Default Pricing Configuration | Setting | Description | Default | |---------|-------------|---------| | `default_pricing_config.mode` | Default pricing strategy for new bundles | `"bundle_led"` | | `default_pricing_config.bundle_led_strategy` | Default discount strategy for bundle-led pricing | `"uniform_percent"` | **Pricing mode options:** | Value | Label | Behavior | |-------|-------|----------| | `"bundle_led"` | **Bundle-led** | The bundle's selling price drives the discount allocation across components | | `"component_led"` | **Component-led** | Component prices are summed to determine the bundle price | **Bundle-led strategy options:** | Value | Label | Behavior | |-------|-------|----------| | `"uniform_percent"` | **Uniform percent** | The same percentage discount is applied to every component | | `"proportional"` | **Proportional** | Discount is distributed proportionally based on each component's retail price | This sets the initial pricing configuration when creating a new bundle. You can change it per bundle. ### Parent-Only (BOM) Settings These settings apply only when the handling mode is `"parent_only"`: | Setting | Description | Default | |---------|-------------|---------| | `parent_only_settings.reserve_timing` | When to reserve component inventory: on order creation or on order payment | `"orders/paid"` | | `parent_only_settings.location_strategy` | Which location to use for inventory reservations | `"fulfillment_order_location"` | | `parent_only_settings.single_location_id` | The specific location ID to use (only when location strategy is `"single_location"`) | None | **Reserve timing options:** | Value | Label | Behavior | |-------|-------|----------| | `"orders/paid"` | **orders/paid** (recommended) | Component inventory is reserved when the order is paid. Reduces the risk of reserving stock for orders that are never completed | | `"orders/create"` | **orders/create** | Component inventory is reserved immediately when the order is created. Use this if you need to lock stock as early as possible (e.g., limited-edition products) | **Location strategy options:** | Value | Label | Behavior | |-------|-------|----------| | `"fulfillment_order_location"` | **Fulfillment order location** (recommended) | Uses the location assigned to the order's fulfillment order. Works well for multi-location setups | | `"single_location"` | **Single location** | Always reserves from a specific location. Useful if all assembly happens at one warehouse | ## Bundle-Level Overrides The following settings can be overridden on individual bundles: - **Handling mode** — Set to a specific mode or leave as "Use store default" - **Inventory sync** — Enable or disable per bundle - **Retail sync** — Enable or disable per bundle - **Pricing configuration** — Fully customizable per bundle ## Related Pages - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [Inventory Rules](/documentation/bundlesiq/inventory-rules) - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) --- ### Handling Modes # Handling Modes Explained Choosing a handling mode is the most important configuration decision in BundlesIQ. It determines how your orders look after bundle processing, which directly affects fulfillment, reporting, accounting, and customer communication. ## What You Will Accomplish After reading this guide, you will understand the four handling modes, what each one does to your orders, and which mode is best for your business. ## When to Use This Guide - You are setting up BundlesIQ for the first time - You are evaluating whether to change your current handling mode - You want to understand the reporting and fulfillment implications of each mode ## The Four Handling Modes ### Hybrid Mode **Best for B2B & Wholesale** Ideal for B2B shops that need to show retailers exactly what they paid and keep clear component-level pricing for fulfillment, reporting, or downstream systems. | What happens | Detail | |-------------|--------| | Bundle line item | Stays on the order at **$0.00** | | Component line items | Added with their **allocated prices** | | Order total | Unchanged from original | **How it works:** - Bundle line item remains on the order at $0 - Individual components are added with their actual prices - Preserves both what was purchased and what was fulfilled **Example order after processing:** ![Hybrid mode Order Preview — bundle at $0, components with allocated prices](/assets/docs/images/bundlesiq/handling-mode-hybrid.png) **Revenue attribution:** Component SKUs --- ### Reporting Mode **Recommended for DTC / B2C** Best when customer clarity and clean revenue reporting matter more than component-level pricing. Accounting stays tied to the bundle SKU while fulfillment still sees the underlying products. | What happens | Detail | |-------------|--------| | Bundle line item | Stays on the order at **its original price** | | Component line items | Added at **$0.00** each | | Order total | Unchanged from original | **How it works:** - Bundle remains on the order with its purchase price - Components are added at $0 - Customer sees exactly what they bought, at the price they paid **Example order after processing:** ![Reporting mode Order Preview — bundle at full price, components at $0](/assets/docs/images/bundlesiq/handling-mode-reporting.png) **Revenue attribution:** Bundle (ghost) SKU --- ### Operational Mode **Best for Distribution & 3PL-driven workflows** Designed for warehouses, distributors, and 3PLs that require strict SKU-level accuracy for picking, packing, inventory sync, and integrations — no bundle abstraction left behind. | What happens | Detail | |-------------|--------| | Bundle line item | **Removed** from the order (quantity set to 0) | | Component line items | Added with their **allocated prices** | | Order total | Unchanged from original | **How it works:** - Bundle is fully removed from the order - Only the priced components remain **Example order after processing:** ![Operational mode Order Preview — only components remain, no bundle line](/assets/docs/images/bundlesiq/handling-mode-operational.png) **Revenue attribution:** Component SKUs --- ### Parent-Only (BOM) Mode — Beta **Best for Made-to-Order & Kitting** Keep the bundle as a single line item while BundlesIQ tracks the underlying components behind the scenes. Ideal when you assemble, kit, or build before shipping — and want a clean order and invoice. | What happens | Detail | |-------------|--------| | Bundle line item | Stays on the order at **its original price** | | Component line items | **Not added** to the order | | Component inventory | **Reserved and consumed automatically** behind the scenes (optional restock on returns) | | Order total | Unchanged from original | **How it works:** - Bundle SKU stays on the order - Components are reserved and consumed automatically (optional restock on returns) - No line-item "explosion" or order edits **Example order after processing:** ![Parent-Only (BOM) mode Order Preview — bundle stays as-is, inventory managed behind the scenes](/assets/docs/images/bundlesiq/handling-mode-bom.png) **Revenue attribution:** Bundle (ghost) SKU > Parent-Only mode is currently in **Beta**. It is fully functional but has v1 limitations: no order edit support, no split fulfillment, and single location strategy is recommended. Additional configuration options may be added in future updates. --- ## Mode Decision Matrix Use this table to identify the right mode for your primary need: | Your priority | Recommended mode | |--------------|-----------------| | "I want fulfillment accuracy and component-level pricing" | **Hybrid** | | "I want my warehouse to see only real SKUs, nothing else" | **Operational** | | "I want revenue attributed to the bundle product" | **Reporting** | | "I sell wholesale and need per-item pricing on invoices" | **Hybrid** | | "I sell DTC and want the customer to see the bundle they bought" | **Reporting** | | "I use a 3PL that imports orders directly" | **Operational** or **Hybrid** | | "I need clean Shopify analytics on bundle performance" | **Reporting** | | "I want both" (fulfillment accuracy + bundle visibility) | **Hybrid** | | "I assemble or kit products and only need inventory reservations" | **Parent-Only (BOM)** | | "I do not want any order editing — just track component stock" | **Parent-Only (BOM)** | ## Quick Decision Guide - **If you ship through a 3PL** — Choose **Operational** (cleanest for 3PL systems) or **Hybrid** (if you need the bundle reference) - **If you sell wholesale** — Choose **Hybrid** (retailers need to see per-item costs) - **If you sell DTC** — Choose **Reporting** (customers see the bundle they bought) - **If you assemble, kit, or manufacture to order** — Choose **Parent-Only (BOM)** (no order editing; component inventory is managed behind the scenes) - **If you are unsure** — Start with **Hybrid** (default). It provides the most flexibility and can be changed later ## How to Set Your Handling Mode ### Store Default 1. **Navigate** to **BundlesIQ > Settings** 2. **Select** your preferred mode under **Default Handling Mode** 3. **Click** **Save** ### Per-Bundle Override 1. **Open** a bundle in **BundlesIQ > Bundles** 2. **Change** the **Handling Mode** dropdown to a specific mode (or leave as "Use store default") 3. **Click** **Save** ## What the Customer Sees In all four modes, the customer's checkout experience is identical — they purchase the bundle product at its listed price. The transformation happens after checkout, so: - The customer's order confirmation email shows the **original bundle line item** (the transformation has not happened yet at email send time in most cases) - If you use Shopify's order status page and the transformation completes quickly, customers may see the transformed order > If customer-facing order clarity is important to you, **Reporting mode** and **Parent-Only mode** preserve the most familiar view for the customer, since the order appears exactly as placed. ## Changing Modes Later You can change your handling mode at any time, and you can override the handling mode per bundle. The change applies to **new orders only** — previously processed orders are not retroactively modified. ## Common Mistakes - **Choosing Operational when you need bundle-level reporting** — If your sales team tracks bundle performance in Shopify Analytics, Operational mode will attribute revenue to component SKUs instead - **Choosing Reporting when your 3PL needs priced line items** — Some 3PLs expect all items to have prices for customs declarations. $0 component lines may cause issues - **Choosing Parent-Only when your 3PL needs component line items** — Parent-Only does not add component lines to the order. If your warehouse picks from line items, use Hybrid, Operational, or Reporting instead - **Not testing with a real order before going live** — Always place a test order and verify the result matches your expectations. See [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) ## Related Pages - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [How Orders Look in Each Mode](/documentation/bundlesiq/order-representation) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) - [Global Settings Overview](/documentation/bundlesiq/global-settings) --- ### Pricing Strategy # Pricing Strategy Setup Your pricing strategy determines how the bundle price relates to the component prices and how discounts are calculated during order transformation. This guide explains both strategies and helps you choose the right one. Set the default pricing strategy for new bundles and configure sync behavior. Each bundle can be individually configured, so you can always override the default. ## What You Will Accomplish After reading this guide, you will understand how bundle-led and component-led pricing work, how discounts are allocated, and which strategy fits your business. ## When to Use This Guide - You are creating a new bundle and need to choose a pricing approach - You want to understand how prices appear on transformed orders - You need to troubleshoot why a component price looks different than expected ## Key Concept: Pricing Strategy and Handling Mode Are Independent Your pricing strategy controls **how prices are calculated**. Your handling mode controls **how the order looks**. You can use any pricing strategy with any handling mode. For example, you can use bundle-led pricing with Reporting mode — BundlesIQ still calculates the correct component prices internally (for catalog management and flagging), even though components appear at $0 on the order. > **Parent-Only (BOM) mode note:** Parent-Only mode uses bundle-led pricing by default. Pricing and retail sync are pre-configured and cannot be changed during onboarding. No component line items are added to the order and no price allocation is applied during order transformation. However, your pricing strategy still determines the ghost SKU's retail price (if retail sync is enabled) and is used for internal cost tracking and the price preview in the BundlesIQ app. ## The Two Pricing Modes | Value | Label | Description | |-------|-------|-------------| | `"bundle_led"` | **Bundle-Led** | Bundle price is fixed, discounts allocated to components. The bundle total determines the component prices (top-down) | | `"component_led"` | **Component-Led** | Component prices determine the bundle total. Each component's price rolls up into the bundle price (bottom-up) | --- ## Bundle-Led Pricing ![Bundle-Led pricing flow — bundle price determines component allocation](/assets/docs/images/bundlesiq/bundle-led-pricing.png) **Bundle price is fixed — discounts are allocated to components.** Use this when your marketing or sales team sets the bundle price and you want components to share that price proportionally. ### How It Works 1. You set the bundle's retail price on the Shopify product (e.g., $99.00) 2. BundlesIQ calculates how much of a discount each component needs so that the sum of component prices equals the bundle price 3. During order transformation, BundlesIQ adds each component with a discount that achieves the target price ### Discount Allocation Strategies for Bundle-Led | Value | Label | Description | |-------|-------|-------------| | `"uniform_percent"` | **Uniform Percent** | Same percentage discount applied to every component | | `"proportional"` | **Proportional** | Distribute discount proportionally by component value | #### Uniform Percent The same percentage discount is applied to every component. **Example:** ``` Bundle retail price: $80.00 Components: Item A: $60.00 retail Item B: $40.00 retail Sum: $100.00 Discount = 1 - ($80 / $100) = 20% After transformation: Item A: $60.00 - 20% = $48.00 Item B: $40.00 - 20% = $32.00 Total: $80.00 ✓ ``` Each component shows the same discount percentage on the order line. #### Proportional Allocation The bundle price is distributed across components based on their retail value as a proportion of the total. **Example:** ``` Bundle retail price: $80.00 Components: Item A: $60.00 retail (60% of total) Item B: $40.00 retail (40% of total) Sum: $100.00 After transformation: Item A: $80.00 × 60% = $48.00 Item B: $80.00 × 40% = $32.00 Total: $80.00 ✓ ``` > Uniform percent and proportional produce the same final prices but differ in how the discount is displayed. Uniform shows "20% off" on each line. Proportional shows the allocated price directly. ### When to Use Bundle-Led - Your bundle has a fixed promotional price ("$99 Summer Bundle") - You want a simple, predictable pricing model - Component prices may change but the bundle price should stay the same - You prefer to set the price at the bundle level --- ## Component-Led Pricing ![Component-Led pricing flow — component prices roll up to the bundle total](/assets/docs/images/bundlesiq/component-led-pricing.png) **Component prices determine the bundle total.** Use this when different components need different discount treatments, or when you want the bundle price to automatically update when component prices change. ### How It Works 1. You set a discount for each component individually (or apply a uniform percent to all) 2. The bundle's retail price is automatically calculated as the sum of all component bundle prices 3. If retail sync is enabled, BundlesIQ updates the ghost SKU's price in Shopify to match ### Discount Strategies for Component-Led | Value | Label | Description | |-------|-------|-------------| | `"uniform_percent"` | **Uniform Percent** | Apply same discount percentage to all components | | `"per_component"` | **Per Component** | Configure individual discounts for each component | #### Uniform Percent Same percentage discount applied to all components (simplest option). **Example:** ``` Uniform discount: 15% Components: Item A: $60.00 retail → $51.00 Item B: $40.00 retail → $34.00 Bundle price (derived): $85.00 ``` #### Per-Component: Percent Off Each component has a different percentage discount. **Example:** ``` Components: Item A: $60.00 retail, 25% off → $45.00 Item B: $40.00 retail, 10% off → $36.00 Bundle price (derived): $81.00 ``` #### Per-Component: Dollar Off Each component has a fixed dollar discount. **Example:** ``` Components: Item A: $60.00 retail, $15 off → $45.00 Item B: $40.00 retail, $5 off → $35.00 Bundle price (derived): $80.00 ``` #### Per-Component: Specific Retail Each component is set to an explicit bundle price. **Example:** ``` Components: Item A: $60.00 retail → set to $45.00 Item B: $40.00 retail → set to $35.00 Display Stand: $30.00 retail → set to $0.00 (free with bundle) Bundle price (derived): $80.00 ``` This is particularly useful for free items in a bundle, such as display stands, samples, or promotional add-ons. ### When to Use Component-Led - Different components should have different discounts - Some components should be free (displays, samples) - You sell wholesale and need transparent per-item pricing on invoices - You want the bundle price to auto-update when component retail prices change in Shopify --- ## Pricing Strategy Decision Matrix | Your scenario | Recommended strategy | |--------------|---------------------| | Fixed promotional bundle price (e.g., "$99 Holiday Set") | **Bundle-led** | | Simple, same discount for all components | **Bundle-led** (uniform percent) or **Component-led** (uniform percent) | | Different discounts per component | **Component-led** (per-component) | | Free items in the bundle (display units, samples) | **Component-led** (specific retail: $0) | | Wholesale with line-item invoice visibility | **Component-led** | | Bundle price should auto-update when component prices change | **Component-led** | ## Retail Sync Behavior by Pricing Mode Retail sync (`sync_bundle_retail`) behaves differently depending on your pricing mode. This is an important distinction: | Pricing Mode | Retail Sync Enabled | Retail Sync Disabled | |-------------|--------------------|--------------------| | **Component-Led** | Bundle price recalculates automatically as the sum of (component retail × qty × discount) | Orders are flagged with a warning if component prices change. Manual review required | | **Bundle-Led** | Bundles are flagged for review when component prices change (the bundle price itself does not auto-update, since it is fixed) | No action taken when component prices change | > In bundle-led mode, retail sync does not change your bundle price — it monitors component prices and flags bundles where the discount math may have shifted. In component-led mode, retail sync actively recalculates and updates the ghost SKU's price in Shopify. ## Rounding and Variance When BundlesIQ allocates prices across components, small rounding differences can occur (typically 1-10 cents). BundlesIQ handles this automatically: 1. **Variance absorber** (enabled by default) — Adjusts a component's discount by a fraction of a cent to eliminate the difference. Operates within configurable thresholds: up to 30 cents total per order and 10 cents per individual line item 2. **Allocation line** (fallback) — If the variance is too large for the absorber but below a critical threshold, BundlesIQ adds a small "Bundle Allocation" line item to reconcile the total In both cases, the order total matches the original bundle price exactly. **Variance absorber ON** — the absorber automatically adjusts a component to eliminate the rounding difference: ![Variance Preview with absorber ON — rounding variance resolved automatically](/assets/docs/images/bundlesiq/variance-absorber-on.png) **Variance absorber OFF** — the variance remains and requires manual reconciliation: ![Variance Preview with absorber OFF — manual reconciliation required](/assets/docs/images/bundlesiq/variance-absorber-off.png) ## How to Configure ### Set the Default Pricing Strategy 1. **Navigate** to **BundlesIQ > Settings** 2. **Under** **Default Pricing Configuration**, select `"bundle_led"` or `"component_led"` 3. **Choose** a discount strategy (`"uniform_percent"` or `"proportional"` for bundle-led; `"uniform_percent"` or `"per_component"` for component-led) 4. **Click** **Save** ### Set Pricing Per Bundle 1. **Open** a bundle in **BundlesIQ > Bundles** 2. **In the pricing section**, select your pricing mode and strategy 3. **If using per-component discounts**, set the discount type and value for each component in the components editor 4. **Review** the price preview to confirm the math 5. **Click** **Save** ## Pricing Warnings and Flags BundlesIQ will warn you about problematic pricing configurations: | Warning | Meaning | What to Do | |---------|---------|-----------| | **Bundle price exceeds component sum** | Bundle-led: your bundle price is higher than the sum of component retail prices. Customers would pay more for the bundle than buying items separately | Lower the bundle price or switch to component-led pricing | | **Dollar discount exceeds retail** | Component-led: a dollar-off discount is greater than the component's retail price | Reduce the discount amount or use "specific retail: $0" instead | | **Specific retail exceeds contextual price** | Component-led: you set a specific retail higher than the component's current Shopify price | Lower the specific retail value | | **Price increase not possible** | At order time, BundlesIQ could not apply the calculated price because Shopify's Order Edit API does not allow increasing a line item's effective price | Review your pricing configuration. The component was added at its Shopify retail price instead | ## How Discounts Appear on Orders In Hybrid and Operational modes, discounts are shown explicitly on component line items: ``` Component Line Item: Original Price: $60.00 Discount: -$12.00 (Bundle allocation) Final Price: $48.00 ``` In Reporting mode, components appear at $0 regardless of pricing strategy. In Parent-Only (BOM) mode, no component line items appear on the order at all — the bundle line stays at the original purchase price. ## Common Mistakes - **Setting bundle price higher than component sum in bundle-led mode** — BundlesIQ cannot increase prices through the Order Edit API. If this happens, components are added at their full retail price and the discrepancy is flagged - **Forgetting to update per-component discounts after retail price changes** — If a component's Shopify price changes, review bundles using "specific retail" discounts to ensure they still make sense - **Mixing up pricing strategy and handling mode** — Remember: pricing strategy = how prices are calculated. Handling mode = how the order looks. They are independent settings - **Assuming retail sync auto-updates the bundle price in bundle-led mode** — In bundle-led mode, retail sync flags bundles for review but does not change the bundle price. Only component-led pricing auto-updates the bundle price ## Related Pages - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [How Orders Look in Each Mode](/documentation/bundlesiq/order-representation) - [Inventory Rules](/documentation/bundlesiq/inventory-rules) - [Troubleshooting: Discount or Price Looks Wrong](/documentation/bundlesiq/troubleshooting) --- ### Inventory Rules # Inventory Rules and Bundle Availability BundlesIQ derives bundle availability from component stock levels, ensuring bundles show as out of stock when any required component runs out. This guide explains how inventory works and how to configure it. ## What You Will Accomplish After reading this guide, you will understand how BundlesIQ calculates bundle availability, how inventory sync works, and what to expect in common scenarios. ## When to Use This Guide - You are setting up a new bundle and want to understand inventory behavior - A bundle is showing as out of stock and you need to understand why - You want to decide whether to enable or disable inventory sync ## How Bundle Availability Is Calculated BundlesIQ uses the **least available component** formula: ``` bundle_availability = min(component_available / qty_per_bundle) ``` For each component, BundlesIQ divides the available inventory by the quantity needed per bundle, then takes the minimum across all components. This ensures you cannot sell more bundles than your lowest-stock component allows. **Example:** ``` Bundle: "Starter Kit" (contains 3 items) Item A: 100 available, 2 per bundle → 100 / 2 = 50 Item B: 30 available, 1 per bundle → 30 / 1 = 30 Item C: 200 available, 5 per bundle → 200 / 5 = 40 Bundle availability = min(50, 30, 40) = 30 bundles ``` In this example, Item B is the bottleneck — you can only sell 30 bundles before Item B runs out. ## Inventory Sync When inventory sync (`sync_bundle_inventory`: `true`) is enabled, BundlesIQ automatically updates the ghost SKU's inventory level in Shopify to match the calculated bundle availability. > Inventory sync is only applicable if you are tracking inventory on the bundle product itself. If the ghost SKU has inventory tracking disabled, Shopify treats it as always in stock and inventory sync has no effect. ### How It Works 1. Shopify fires an `inventory_levels/update` webhook when any product's inventory changes 2. BundlesIQ checks whether the updated variant is a component of any active bundles (using the component bundle index) 3. For each affected bundle, BundlesIQ recalculates availability using the least-available-component formula 4. BundlesIQ updates the ghost SKU's inventory level in Shopify to match the new availability ### Enabling or Disabling Inventory Sync **Store-level default:** 1. **Navigate** to **BundlesIQ > Settings** 2. **Toggle** **Sync bundle inventory** (`sync_bundle_inventory`) on or off 3. **Click** **Save** **Per-bundle override:** 1. **Open** a bundle in **BundlesIQ > Bundles** 2. **Toggle** **Sync inventory** on or off 3. **Click** **Save** ### When to Enable Inventory Sync - You want bundles to automatically show as out of stock when components run low - You rely on Shopify's "Continue selling when out of stock" setting to control availability - You want your storefront to reflect accurate bundle availability without manual updates ### When to Disable Inventory Sync - You manage bundle availability manually in Shopify - Your ghost SKU has inventory tracking disabled (Shopify treats it as always in stock) - You have a separate system that manages ghost SKU inventory ## Retail Sync Retail sync (`sync_bundle_retail`: `true`) automatically updates bundle pricing when component prices change. **Behavior varies based on pricing mode:** | Pricing Mode | Retail Sync Enabled | Retail Sync Disabled | |-------------|--------------------|--------------------| | **Component-Led** | Bundle price recalculates automatically as the sum of (component retail × qty × discount) | Orders are flagged with a warning if component prices change. Manual review required | | **Bundle-Led** | Bundles are flagged for review when component prices change (the bundle price itself does not auto-update, since it is fixed) | No action taken when component prices change | ### Enabling or Disabling Retail Sync **Store-level default:** 1. **Navigate** to **BundlesIQ > Settings** 2. **Toggle** **Sync bundle retail** (`sync_bundle_retail`) on or off 3. **Click** **Save** **Per-bundle override:** 1. **Open** a bundle in **BundlesIQ > Bundles** 2. **Toggle** **Sync retail** on or off 3. **Click** **Save** > Retail sync is recommended for most stores. In component-led mode, it keeps your bundle price accurate. In bundle-led mode, it alerts you when the discount math may have shifted. ## Ghost SKU Inventory Tracking For inventory sync to work correctly, the ghost SKU product variant should have one of these configurations: | Configuration | Behavior | |--------------|----------| | **Inventory tracked, managed by BundlesIQ** (recommended) | BundlesIQ sets the available quantity based on components. Shopify enforces out-of-stock rules | | **Inventory not tracked** | The bundle is always shown as in stock on the storefront. BundlesIQ still processes orders but does not control availability | > We recommend enabling inventory tracking on the ghost SKU and letting BundlesIQ manage the quantity. This ensures customers cannot purchase bundles when components are out of stock. ## What Happens When a Component Hits Zero When any component's available inventory drops to zero: 1. BundlesIQ recalculates the bundle availability as **0** 2. If inventory sync is enabled, BundlesIQ sets the ghost SKU's inventory to **0** 3. If the ghost SKU has "Continue selling when out of stock" **disabled** (recommended), the bundle product shows as **Out of stock** on your storefront 4. If "Continue selling when out of stock" is **enabled**, customers can still purchase the bundle, but the order may not be fulfillable ## Shopify's "Continue Selling When Out of Stock" Setting This Shopify setting on the ghost SKU variant controls what happens when inventory reaches zero: | Setting | Effect | |---------|--------| | **Disabled** (recommended) | Bundle cannot be purchased when inventory is 0. Prevents overselling | | **Enabled** | Bundle can still be purchased at 0 inventory. Useful for pre-orders or made-to-order scenarios, but risks overselling components | > Set this on the **ghost SKU variant** in Shopify Admin under **Products > [Bundle Product] > Inventory**. ## Inventory After an Order ### Hybrid, Reporting, and Operational Modes When a customer purchases a bundle: - **Component inventory** is decremented by Shopify as part of its normal order fulfillment flow (because BundlesIQ adds component line items to the order) - **Bundle inventory** is recalculated by BundlesIQ when the component inventory webhook fires, reflecting the reduced component stock This means inventory stays consistent — selling a bundle reduces both the component stock and the derived bundle availability. ### Parent-Only (BOM) Mode In Parent-Only mode, BundlesIQ does not add component line items to the order, so Shopify's normal fulfillment flow does not decrement component stock. Instead, BundlesIQ manages component inventory through Shopify's inventory state API: | Event | Inventory Action | |-------|-----------------| | **Order created or paid** (depending on `reserve_timing`) | Component stock moves from `available` to `reserved` | | **Order fulfilled** | `reserved` stock is consumed (decremented) | | **Order cancelled** | `reserved` stock is released back to `available` | | **Return/restock** | Stock is restocked to `available` | **The inventory lifecycle:** ``` Order placed → Component: 100 available, 2 reserved Order fulfilled → Component: 100 available, 0 reserved (2 consumed) -- OR -- Order cancelled → Component: 102 available, 0 reserved (2 released) ``` This approach ensures component stock is tracked accurately without modifying the order itself. The ghost SKU's inventory sync still works the same way — bundle availability is recalculated based on component `available` quantities. > In Parent-Only mode, `reserved` quantities reduce the effective available stock. A component with 100 available and 10 reserved has 90 units effectively available for new orders. BundlesIQ factors this into bundle availability calculations. ## Shared Components Across Bundles If the same component variant appears in multiple bundles, all bundles that share that component are affected when its inventory changes. **Example:** ``` Bundle A: Contains Item X (2 per bundle) Bundle B: Contains Item X (3 per bundle) Item X: 60 available Bundle A availability from Item X: 60 / 2 = 30 Bundle B availability from Item X: 60 / 3 = 20 ``` BundlesIQ calculates each bundle's availability independently. Selling Bundle A reduces Item X's stock, which triggers a recalculation for both Bundle A and Bundle B. ## Multi-Location Inventory BundlesIQ calculates bundle availability at the **location level** when your store uses multiple Shopify locations. The ghost SKU's inventory is updated per location based on component availability at that location. > Multi-location inventory adds complexity. We recommend testing with a single location first and expanding to multiple locations once you have confirmed basic bundle inventory behavior. ## Troubleshooting Inventory Issues | Issue | Possible Cause | Solution | |-------|---------------|----------| | Bundle shows out of stock but components have inventory | One component has 0 available inventory at the relevant location | Check all components' inventory levels. The bottleneck component determines availability | | Bundle inventory does not update after component changes | Inventory sync is disabled for this bundle or at the store level | Enable inventory sync in settings or on the bundle | | Bundle inventory is higher than expected | Ghost SKU inventory was manually set and is not being overwritten | Ensure inventory sync is enabled and the ghost SKU's inventory is managed by BundlesIQ | | Bundle shows in stock but a component is at 0 | "Continue selling when out of stock" is enabled on the ghost SKU | Disable this setting on the ghost SKU variant if you want to prevent overselling | | (Parent-Only) Component `reserved` quantity not increasing | Reserve timing is set to `"orders/paid"` but the order has not been paid yet | Wait for payment, or change reserve timing to `"orders/create"` | | (Parent-Only) Component stock not released after cancellation | The cancellation event was not received by BundlesIQ | Check the Health dashboard and manually trigger a re-evaluation if needed | ## Common Mistakes - **Leaving "Continue selling when out of stock" enabled on the ghost SKU** — This allows customers to buy bundles even when components are unavailable - **Manually setting ghost SKU inventory** — If inventory sync is enabled, BundlesIQ will overwrite your manual changes on the next sync cycle - **Not checking all component inventory levels** — Bundle availability is limited by the single lowest component. Check every component when debugging stock issues - **Assuming retail sync auto-updates the bundle price in bundle-led mode** — In bundle-led mode, retail sync flags bundles for review but does not change the bundle price. Only component-led pricing auto-updates the bundle price. See [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) for details ## Related Pages - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [Troubleshooting: Bundle Shows Out of Stock](/documentation/bundlesiq/troubleshooting) - [Global Settings Overview](/documentation/bundlesiq/global-settings) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) --- ### Create a Bundle # Create and Manage Bundles This guide walks you through creating, editing, and managing bundles in BundlesIQ. > BundlesIQ operates **variant-to-variant**. Shopify Admin often talks in “products,” but BundlesIQ detects and maps using **variant IDs**. --- ## What You Will Accomplish You will: * Create a bundle by linking a **ghost SKU variant** (the bundle item customers buy) to **component variants** * Configure pricing and (optional) constraints * Configure (optional) inventory/retail sync settings * Activate the bundle and run the built-in **Test Bundle** flow ![BundlesIQ bundle editor showing ghost SKU, components, pricing, and status](/assets/docs/images/bundlesiq/create-bundle-screen.png) --- ## Before You Begin * Your **component variants already exist in Shopify** (BundlesIQ can create the ghost SKU item in-app, but **components must exist in Shopify**) * You have a basic idea of your store’s default: * Handling mode (Operational / Hybrid / Reporting / Parent-Only (BOM)) * Pricing mode (Bundle-Led / Component-Led) --- ## Step 1: Open the Bundle Creator 1. **Navigate** to **BundlesIQ > Bundles** in your Shopify Admin sidebar 2. **Click** **Create Bundle** (top-right) --- ## Step 2: Configure Bundle Info & Defaults In the **Info & Configuration** card: 1. **Give the bundle a name** * Internal reference only (recommended: similar to the ghost SKU item name) 2. **(Optional) Pricing Mode** * Defaults to your shop’s default (collapsed section; can be overridden per bundle) 3. **(Optional) Handling Mode** * Defaults to your shop’s default (collapsed section; can be overridden per bundle) --- ## Step 3: Select or Create the Ghost SKU Variant + Add Components All bundle composition happens in the **Bundle Components** card. ### 3A) Select or create the Ghost SKU variant The **ghost SKU variant** is the bundle variant customers purchase. Choose one: * **Select Product From Shopify** → pick an existing Shopify variant, or * **Create New Item** → create the bundle item from inside BundlesIQ (fastest path) > **Note:** SKU is optional. BundlesIQ identifies items by **variant ID**, not SKU. ### 3B) Add components Components are the individual **variants** included in the bundle. You can add components two ways: #### Option 1: Add Components (search + add) 1. **Click** **Add Components** 2. **Search** and select a component **variant** 3. **Set** the **Quantity per bundle** 4. **(Optional)** Mark as **Required** 5. Repeat for each component #### Option 2: Import CSV (bulk append) 1. **Click** **Import CSV** 2. Download the template 3. Paste one identifier per line into `identifier`: * SKU, barcode, variant ID, or Shopify GID 4. Enter the per-bundle quantity in `quantity` * Defaults to **1** if omitted ![Bundle components editor with ghost SKU, component variants, quantities, and pricing](/assets/docs/images/bundlesiq/create-bundle-setting-components.png) **Component fields:** | Field | Description | | ----------------------- | ------------------------------------------------------------------------------ | | **Variant** | The Shopify variant to include | | **Quantity per bundle** | Units included per bundle (e.g., 2 if the bundle contains 2 of this component) | | **Required** | If enabled, staff cannot remove this component during adjustments | | **Sort order** | Controls display order in the bundle editor | --- ## Step 4: Configure Pricing BundlesIQ supports different pricing strategies depending on your **Pricing Mode** and **Handling Mode**. ### Pricing Modes #### Bundle-Led * The **ghost SKU variant price** is the bundle price customers pay. * BundlesIQ allocates that bundle price across components during transformation. **Important constraint (avoid impossible allocations):** * The sum of component retail values (qty × price) must be **>=** the bundle price. * Reason: you can reliably discount/allocate down; you can’t reliably “increase” a component’s effective price beyond its retail. #### Component-Led * Component pricing is defined at the component level using options like: * **No Discount** * **Percent Off** * **Amount Off** * **Fixed Price** **Fixed Price constraint:** * Fixed Price must be **<=** the component’s retail price. ### Parent-Only (BOM) note If your handling mode is **Parent-Only (BOM)**: * The order typically does **not** expand into component line items * Pricing is treated differently (cost/profit/margin workflow) --- ## Step 5: Set Constraints (Optional) Constraints limit how staff can adjust components on a specific order (when your workflow allows staff adjustments). | Constraint | Description | Example | | --------------------------- | ------------------------------------------------------------- | ---------------------------------------------- | | **Total quantity required** | Total units across all components must equal this value | A 24-unit case pack must always total 24 units | | **Max component delta** | Max deviation allowed per component from its default quantity | A component can deviate by up to 10 units | Leave constraints empty if you don’t need restrictions. --- ## Step 6: Add BOM Cost Lines (Parent-Only Mode Only) If the bundle uses **Parent-Only (BOM)** handling mode, you can add cost lines for internal tracking: 1. **Scroll** to **BOM Cost Lines** (only visible in Parent-Only) 2. **Click** **Add Cost Line** 3. Enter a **Name** and **Amount** | Field | Description | Example | | ---------- | ----------- | -------------------------------- | | **Name** | Cost label | “Labor”, “Overhead”, “Packaging” | | **Amount** | Dollar cost | $5.00 | > BOM cost lines are internal-only. They do not appear on the Shopify order or change what customers pay. --- ## Step 7: Advanced Settings (Optional) In the **Advanced Settings** card you may see options such as: * **Sync Bundle Inventory** * **Sync Bundle Retail** (commonly relevant for Component-Led setups) * **Storefront UI** (e.g., “What’s Included” display on product page) ### Inventory tracking reality (important) * If you enable **Sync Bundle Inventory**, the ghost SKU variant must have **inventory tracking ON** in Shopify. * If you want Shopify to prevent overselling the bundle variant: * Track inventory **ON** * “Continue selling when out of stock” **OFF** * Then let BundlesIQ sync availability based on component availability (if enabled) ![Advanced Settings card showing Sync Bundle Retail, Show Components on Storefront, and theme setup instructions](/assets/docs/images/bundlesiq/create-bundle-advanced-settings-card.png) If you enable **Show Components on Storefront**, you'll need to add the BundlesIQ theme block to your product page template: ![Adding the BIQ: What's Included block in the Shopify theme editor](/assets/docs/images/bundlesiq/adding-theme-extension.png) Once configured, customers see the bundle's component list on the product page: ![Storefront product page showing the What's Included section with component variants](/assets/docs/images/bundlesiq/theme-extension-example.png) > For step-by-step instructions on adding the product page and cart blocks through the Shopify theme editor, see [Storefront Blocks](/documentation/bundlesiq/storefront-blocks). --- ## Step 8: Review, Save, and Activate 1. Review the summary (including any pricing/validation warnings) 2. Set status to **Active** if you want BundlesIQ to begin processing orders for this bundle 3. Click **Save** --- ## Step 9: Test the Bundle (Recommended) After saving and activating, click **Test Bundle** at the top of the bundle page. The test runs a safe validation flow to confirm processing works end-to-end. **High-level, Test Bundle:** 1. Creates a draft order (validates webhook reception + pipeline) 2. Verifies transformation output matches your configuration 3. Verifies bundle metadata/metafields were written 4. Deletes the draft order (keeps your store clean) --- ## Bundle Statuses | Status | Meaning | | ------------ | ----------------------------------------------------------------------------------- | | **Active** | BundlesIQ will detect and process orders containing this bundle’s ghost SKU variant | | **Inactive** | Bundle is preserved but BundlesIQ will not process orders for it | | **Draft** | Bundle is being configured and is not ready for processing | | **Archived** | Bundle is hidden from the main list and treated as no longer in use | --- ## Editing an Existing Bundle 1. Navigate to **BundlesIQ > Bundles** 2. Click the bundle you want to edit 3. Make changes (components, pricing, constraints, settings) 4. Click **Save** 5. Run **Test Bundle** to confirm everything still transforms as expected > By default, configuration changes apply to **new orders**. Previously processed orders are not retroactively modified unless you explicitly reprocess. --- ## Common Mistakes * **Selecting the wrong variant** — If a product has multiple variants (sizes, colors), select the correct variant for both the ghost SKU and components * **Forgetting to set the bundle to Active** — Draft/Inactive bundles won’t process orders * **Misconfigured inventory expectations** — Sync Bundle Inventory requires inventory tracking ON for the ghost SKU * **Not running Test Bundle after changes** — Always run **Test Bundle** after editing to catch issues before customers do --- ## Related Pages * [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) * [Price Preview](/documentation/bundlesiq/price-preview) * [Storefront Blocks](/documentation/bundlesiq/storefront-blocks) * [Quickstart Guide](/documentation/bundlesiq/quickstart) --- ### Price Preview # Price Preview and Savings Math BundlesIQ provides a price preview when creating or editing a bundle so you can verify that pricing calculations are correct before going live. This guide explains how to interpret the preview. ## What You Will Accomplish You will understand how to read the price preview in the bundle editor and verify that your pricing configuration produces the expected results. ## The Price Preview Section When you create or edit a bundle, the price preview displays: ![Price Preview panel — bundle retail, per-component discounts, allocated prices, and total savings](/assets/docs/images/bundlesiq/price-preview.png) The price preview panel shows: - Bundle retail price (ghost SKU price) - Sum of component retail prices - Discount applied to each component - Final price per component - Total after allocation - Savings amount and percentage ## Reading the Preview: Bundle-Led Pricing For bundle-led pricing, the preview shows: | Field | Meaning | |-------|---------| | **Bundle retail** | The price set on the ghost SKU product in Shopify | | **Component sum** | The total of all component retail prices multiplied by their quantities | | **Effective discount** | The discount percentage needed to bring the component sum down to the bundle retail | | **Per-component breakdown** | Each component's retail price, discount amount, and resulting bundle price | | **Total after allocation** | Should match the bundle retail exactly | **Example:** ``` Bundle: Summer Essentials Retail: $99.00 ───────────────────────────────────────────── Component Retail Discount Bundle Price Sunglasses (x1) $50.00 -17.5% $41.25 Beach Towel (x1) $40.00 -17.5% $33.00 Sunscreen (x1) $30.00 -17.5% $24.75 ───────────────────────────────────────────── Component Sum: $120.00 Total After Alloc: $99.00 ✓ Savings: $21.00 (17.5% off) ``` ## Reading the Preview: Component-Led Pricing For component-led pricing, the preview shows: | Field | Meaning | |-------|---------| | **Per-component breakdown** | Each component's retail price, configured discount, and resulting bundle price | | **Bundle retail (derived)** | The sum of all component bundle prices — this is what the ghost SKU price should be set to | | **Total savings** | The total discount compared to buying components individually | **Example:** ``` Bundle: Starter Kit with Display ───────────────────────────────────────────── Component Retail Discount Bundle Price Product A (x1) $80.00 None $80.00 Product B (x1) $80.00 None $80.00 Display Stand (x1) $40.00 Specific: $0 $0.00 ───────────────────────────────────────────── Bundle Retail (derived): $160.00 Savings: $40.00 (20% off buying separately) ``` ## Warning Indicators The price preview highlights potential issues: | Indicator | Meaning | |-----------|---------| | **Yellow warning** | Bundle price exceeds component sum (would require price increase, which may fail on orders) | | **Red error** | A component discount would result in a negative price or other invalid state | | **Info notice** | Rounding may cause a small variance (1-10 cents) that will be automatically reconciled | ## Verifying Your Pricing Before activating a bundle, check these things in the preview: 1. **Total after allocation matches bundle retail** — The math should add up exactly 2. **No warning indicators** — Resolve any yellow or red flags before going live 3. **Per-component prices look reasonable** — Verify that each component's allocated price makes sense for your invoicing and reporting needs 4. **Quantities are correct** — Each component shows the right quantity per bundle ## Retail Price Sync (Component-Led) If you use component-led pricing and have retail sync enabled, BundlesIQ automatically updates the ghost SKU's Shopify price to match the derived bundle retail. This means: - When you save a bundle with component-led pricing, BundlesIQ calculates the sum of component bundle prices and updates the ghost SKU product's price - If a component's retail price changes in Shopify, BundlesIQ recalculates the derived bundle price and updates the ghost SKU accordingly ## Parent-Only (BOM) Mode In Parent-Only mode, no component price allocation is applied to the order — the bundle line stays at its original price and no component lines are added. However, the price preview is still useful: - It shows the component cost breakdown for internal reference - It verifies that the ghost SKU's retail price matches expectations - If BOM cost lines are configured, they appear in the preview alongside component costs ## Common Mistakes - **Not checking the preview before activating** — Always verify the math in the preview. A misconfigured discount can cause incorrect pricing on real orders - **Ignoring warning indicators** — Yellow and red flags indicate real problems that will affect order processing - **Assuming the preview accounts for Shopify discount codes** — The preview shows bundle pricing only. If a customer applies a Shopify discount code at checkout, the additional discount is applied on top of the bundle allocation ## Related Pages - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [Create and Manage Bundles](/documentation/bundlesiq/create-a-bundle) - [Troubleshooting: Discount or Price Looks Wrong](/documentation/bundlesiq/troubleshooting) --- ### Storefront Blocks # Storefront Blocks BundlesIQ includes optional **theme app blocks** that show a bundle's components to shoppers on your storefront. There are two blocks: - **`BIQ: What's Included`** — displays the bundle's component list on the **product page**. - **`BIQ: Cart Contents`** — displays the bundle's components in the **cart**. This guide explains how to add each block to your theme using the Shopify theme editor. ![Storefront product page with the BIQ: What's Included block listing each bundle component and quantity alongside the product](/assets/docs/images/bundlesiq/storefront-whats-included-preview.png) *Example: the `BIQ: What's Included` block on a live product page, showing each component and quantity.* ## What You Will Accomplish You will add the BundlesIQ storefront blocks to your product page and cart so customers can see exactly what's inside a bundle before and during checkout. ## Before You Start - **Enable the storefront display on the bundle.** Turn on **Show Components on Storefront** in the bundle's Advanced Settings. See [Create and Manage Bundles](/documentation/bundlesiq/create-a-bundle). - **Use an Online Store 2.0 theme.** App blocks require a section-based (OS 2.0) theme. Most current Shopify themes qualify. > **Display only.** These blocks only *show* bundle information to shoppers. They don't change how the cart or order is processed — order transformation happens after checkout. See [How BundlesIQ Works](/documentation/bundlesiq/how-bundlesiq-works). ## Open the Theme Editor In your Shopify admin, go to **Online Store** in the left-hand menu, then click **Edit theme** on the theme you want to update. ![Shopify admin with Online Store selected in the sidebar and the Edit theme button on the live theme](/assets/docs/images/bundlesiq/storefront-online-store-menu.png) Once the theme editor is open, use the **template dropdown** at the top center to switch to the page you want to edit — for example, **Products** or **Cart**. ![Theme editor template dropdown expanded, with Products selected](/assets/docs/images/bundlesiq/storefront-template-dropdown-products.png) ## Add the Product Page Block 1. In the template dropdown, choose **Products** (the default product template). 2. In the left panel under **Template**, click **Add section**. 3. In the picker that opens, switch from the **Sections** tab to the **Apps** tab. Under **Apps** you'll find **`BIQ: What's Included`** (listed under *BundlesIQ - Product Bundles*). Click it to add the block. ![Add section picker on the product template, Apps tab selected, showing the BIQ: What's Included block](/assets/docs/images/bundlesiq/storefront-add-pdp-section-app-biq.png) 4. Drag the section to the position you want, then click **Save**. Once placed, customers see the bundle's component list on the product page: ![Product page in the theme editor showing the What's Included section with sample components](/assets/docs/images/bundlesiq/storefront-place-pdp-section-biq.png) ## Add the Cart Block 1. In the template dropdown, choose **Cart**. 2. In the left panel under **Template**, find the **Apps** area and click **Add block**. 3. In the picker that opens, switch to the **Apps** tab. Under **Apps** you'll find **`BIQ: Cart Contents`** (listed under *BundlesIQ - Product Bundles*). Click it to add the block. ![Add block picker on the cart template, Apps tab selected, showing the BIQ: Cart Contents block](/assets/docs/images/bundlesiq/storefront-add-cart-section-app-biq.png) 4. Drag the block to the position you want, then click **Save**. You can adjust the block's **Section heading** (e.g. "Bundle Details") and **Row heading** (e.g. "What's Included") in the block settings on the left. Once placed, customers see the bundle's components in the cart: ![Cart in the theme editor showing the BIQ: Cart Contents block with bundle details and sample components](/assets/docs/images/bundlesiq/storefront-place-cart-section-biq.png) > In the editor, the block shows sample placeholder data. Real component data appears when an actual bundle is in the cart. ## Repositioning or Removing a Block - **Reposition:** In the theme editor, drag the section/block within its template, then click **Save**. - **Remove:** Select the section/block and click **Remove section** (product page) or **Remove block** (cart), then click **Save**. Removing the block only hides the storefront display — it does not affect bundle processing. ## If the Block Doesn't Appear - Make sure you're editing an **Online Store 2.0** theme (app blocks aren't available in older vintage themes). - Confirm **Show Components on Storefront** is enabled on the bundle. - Confirm you're on the correct template in the top dropdown (the product block lives on the **Products** template; the cart block lives on the **Cart** template). - After adding a block, remember to click **Save** — unsaved blocks won't show on the live storefront. ## Related Pages - [Create and Manage Bundles](/documentation/bundlesiq/create-a-bundle) - [How BundlesIQ Works](/documentation/bundlesiq/how-bundlesiq-works) - [Installation and Permissions](/documentation/bundlesiq/installation) --- ### Order Representation # How Orders Look in Each Handling Mode This guide provides a detailed comparison of what orders look like after BundlesIQ processes them in each handling mode, including the impact on invoices, packing slips, reporting, and downstream systems. ## What You Will Accomplish You will see exactly how each handling mode transforms an order, understand the reporting and fulfillment implications, and know what to expect in your Shopify Admin. ## Side-by-Side Comparison For a bundle called "Summer Essentials" priced at $99.00 containing: - Sunglasses ($50 retail) - Beach Towel ($40 retail) - Sunscreen ($30 retail) Using bundle-led pricing with uniform 17.5% discount: ### Hybrid Mode ![Hybrid mode before and after — bundle zeroed to $0, components added with allocated prices](/assets/docs/images/bundlesiq/health-dashboard-handling-mode-hybrid.png) | Line Item | Qty | Price | Discount | |-----------|-----|-------|----------| | Summer Essentials Bundle | 1 | $0.00 | Set to $0 | | Sunglasses | 1 | $50.00 | -$8.75 (17.5%) = **$41.25** | | Beach Towel | 1 | $40.00 | -$7.00 (17.5%) = **$33.00** | | Sunscreen | 1 | $30.00 | -$5.25 (17.5%) = **$24.75** | | **Total** | | | **$99.00** | ### Operational Mode ![Operational mode before and after — bundle removed, only component SKUs remain](/assets/docs/images/bundlesiq/health-dashboard-handling-mode-operational.png) | Line Item | Qty | Price | Discount | |-----------|-----|-------|----------| | ~~Summer Essentials Bundle~~ | ~~1~~ | — | Removed (qty set to 0) | | Sunglasses | 1 | $50.00 | -$8.75 (17.5%) = **$41.25** | | Beach Towel | 1 | $40.00 | -$7.00 (17.5%) = **$33.00** | | Sunscreen | 1 | $30.00 | -$5.25 (17.5%) = **$24.75** | | **Total** | | | **$99.00** | ### Reporting Mode ![Reporting mode before and after — bundle kept at full price, components at $0](/assets/docs/images/bundlesiq/health-dashboard-handling-mode-reporting.png) | Line Item | Qty | Price | Discount | |-----------|-----|-------|----------| | Summer Essentials Bundle | 1 | **$99.00** | Unchanged | | Sunglasses | 1 | $50.00 | -$50.00 (100%) = **$0.00** | | Beach Towel | 1 | $40.00 | -$40.00 (100%) = **$0.00** | | Sunscreen | 1 | $30.00 | -$30.00 (100%) = **$0.00** | | **Total** | | | **$99.00** | ### Parent-Only (BOM) Mode | Line Item | Qty | Price | Discount | |-----------|-----|-------|----------| | Summer Essentials Bundle | 1 | **$99.00** | Unchanged | | *(No component line items on the order)* | | | | | **Total** | | | **$99.00** | In Parent-Only mode, no order editing occurs. Component inventory is managed behind the scenes: - **On order creation or payment** (depending on reserve timing setting): component stock moves from `available` to `reserved` - **On fulfillment**: reserved stock is consumed (decremented) - **On cancellation**: reserved stock is released back to `available` ### Multi-Bundle Order (Mixed Modes) When a single order contains multiple bundles using different handling modes, BundlesIQ processes each bundle according to its configured mode. The order allocation view shows the full before-and-after transformation: ![Multi-bundle order with Reporting, Hybrid, and Operational modes on a single order](/assets/docs/images/bundlesiq/health-dashboard-multi-handling-modes.png) ## Impact on Invoices and Packing Slips | Aspect | Hybrid | Operational | Reporting | Parent-Only (BOM) | |--------|--------|-------------|-----------|-------------------| | **Invoice shows bundle name** | Yes (at $0) | No | Yes (at full price) | Yes (at full price) | | **Invoice shows component prices** | Yes | Yes | No (all $0) | No (no components on order) | | **Packing slip shows components** | Yes | Yes | Yes | No (only the bundle SKU) | | **Components identifiable as part of a bundle** | Yes (bundle label line visible) | Via order tags/metafields only | Yes (grouped under bundle) | Via BundlesIQ app or order metafield only | ### Identifying Bundle Components on Packing Slips In **Hybrid** and **Reporting** modes, the bundle line item appears alongside the components, making it clear which items belong to the bundle. In **Parent-Only (BOM)** mode, no components appear on the packing slip at all — only the bundle SKU. Your warehouse should use the bundle's bill of materials (available in the BundlesIQ app) or a printed BOM sheet to know which items to pick or assemble. In **Operational** mode, the bundle line is removed. To identify components as part of a bundle on packing slips, you can: - Use the `BIQ_READY` tag to identify bundle-processed orders - Check the `bundles_iq.transformation_audit` order metafield for the full bundle mapping - Use BundlesIQ's bundle header feature (in Writer Options) to add grouping headers to the order ## Impact on Revenue Reporting | Report | Hybrid | Operational | Reporting | Parent-Only (BOM) | |--------|--------|-------------|-----------|-------------------| | **Revenue attributed to** | Component SKUs | Component SKUs | Bundle (ghost) SKU | Bundle (ghost) SKU | | **Best-seller rankings** | Reflect component products | Reflect component products | Reflect bundle product | Reflect bundle product | | **Shopify Analytics "Sales by product"** | Components get credit | Components get credit | Bundle gets credit | Bundle gets credit | | **Collection performance** | Based on components | Based on components | Based on bundle | Based on bundle | > If you need bundle-level revenue reporting in Shopify Analytics, use **Reporting mode** or **Parent-Only mode**. If you need SKU-level reporting, use **Hybrid** or **Operational** mode. ## Impact on Fulfillment | Aspect | Hybrid | Operational | Reporting | Parent-Only (BOM) | |--------|--------|-------------|-----------|-------------------| | **Items to pick/pack** | Component line items | Component line items | Component line items | Bundle line item only (use BOM for picking) | | **Bundle parent visible to warehouse** | Yes (as $0 line) | No | Yes (as priced line) | Yes (only item on the order) | | **3PL sees real SKUs** | Yes | Yes | Yes | No (only the ghost SKU) | | **Potential 3PL confusion** | Low (bundle at $0 is obvious) | None (no bundle reference) | Medium ($0 components may confuse some 3PLs) | High if 3PL expects individual SKUs — use only with internal or BOM-aware warehouses | ## Impact on Discount Codes If a customer applies a Shopify discount code at checkout: - The discount is applied to the original bundle line item at checkout (before BundlesIQ processes the order) - BundlesIQ detects the applied promo discount and factors it into the component price calculations - In **Hybrid** and **Operational** modes, the promo discount is distributed across components along with the bundle allocation discount - In **Reporting** mode, the promo discount stays on the bundle line and components remain at $0 - In **Parent-Only (BOM)** mode, the promo discount stays on the bundle line as-is (no component lines exist to distribute to) ## Impact on Taxes Tax calculation depends on your Shopify tax settings: - **Tax-exclusive stores** — Taxes are calculated on the final line item prices after discounts. Each component is taxed at its allocated price - **Tax-inclusive stores** — BundlesIQ preserves the tax-inclusive pricing during allocation In all modes, the total tax collected should match what the customer was charged at checkout, because BundlesIQ preserves the order total. ## What the Customer Sees | Touchpoint | What the Customer Sees | |-----------|----------------------| | **Checkout** | The original bundle product at the bundle price (transformation has not happened yet) | | **Order confirmation email** | Usually the original bundle product (email is sent before transformation in most cases) | | **Order status page** | The transformed order (if they check after processing completes) | | **Account order history** | The transformed order | > In **Reporting mode** and **Parent-Only mode**, the customer sees the bundle name and price in their order history, which is the most familiar experience. In **Hybrid** and **Operational** modes, the customer sees component line items. ## Related Pages - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) --- ### Draft Orders # Draft Orders and B2B Workflows BundlesIQ processes bundles in Shopify draft orders, making it compatible with B2B, wholesale, and manual order creation workflows. ## What You Will Accomplish You will understand how BundlesIQ handles draft orders, what to expect during the B2B workflow, and how draft order processing differs from standard order processing. ## When to Use This Guide - You create draft orders for wholesale or B2B customers - You use Shopify's B2B features (company accounts, price lists) - You want to understand the timing and behavior of bundle processing on draft orders ## Enabling Draft Order Processing Draft order processing is controlled in your global settings: 1. **Navigate** to **BundlesIQ > Settings** 2. **Ensure** **Process draft orders** is **enabled** 3. **Click** **Save** ## How Draft Order Processing Works ### Detection BundlesIQ subscribes to Shopify's `draft_orders/create` and `draft_orders/update` webhooks. When a draft order is created or updated and contains a bundle ghost SKU, BundlesIQ detects it and begins processing. ### Transformation Draft order transformation works the same as standard order transformation: 1. BundlesIQ detects bundle line items 2. Loads the bundle configuration, components, and pricing 3. Calculates price allocations based on your pricing strategy 4. Transforms the draft order by adding component line items and applying discounts ### Key Difference: API Method | Order Type | Transformation Method | |-----------|----------------------| | Standard orders (Hybrid/Reporting/Operational) | Shopify Order Edit API (begin → add lines → apply discounts → commit) | | Draft orders (Hybrid/Reporting/Operational) | Shopify `draftOrderUpdate` mutation (direct line item replacement) | | Standard or draft orders (Parent-Only/BOM) | No order editing — inventory reservation via Shopify inventory state API | Draft orders use a simpler API that allows direct price setting on line items, which means: - **Price increases are possible** on draft orders (unlike the Order Edit API for standard orders) - **No calculated order workflow** — Changes are applied directly - **Full price control** — BundlesIQ can set exact prices per component without relying on discounts ## The B2B Workflow A typical B2B workflow with BundlesIQ: ### 1. Create the Draft Order 1. **Open** Shopify Admin > **Orders** > **Drafts** > **Create draft order** 2. **Add** the bundle product (ghost SKU) to the draft order 3. **Set** the customer (optional: associate with a B2B company) 4. **Apply** any relevant discounts or price adjustments ### 2. BundlesIQ Processes the Draft BundlesIQ automatically detects and transforms the draft order. Within a few seconds: - Component line items are added to the draft - Pricing is allocated based on your bundle configuration - The bundle line is handled according to your handling mode ### 3. Review the Transformed Draft 1. **Open** the draft order in Shopify Admin 2. **Verify** the component line items and prices look correct 3. **Make** any manual adjustments if needed (you can still edit the draft) ### 4. Complete the Draft Order When ready, complete the draft order by: - **Sending an invoice** to the customer for payment - **Marking as paid** (for pre-negotiated terms) - **Accepting payment** directly > If you edit the draft order after BundlesIQ processes it and add another bundle product, BundlesIQ will re-process the draft when the `draft_orders/update` webhook fires. ![Accessing Bundle Tools from the draft order More actions menu in Shopify Admin](/assets/docs/images/bundlesiq/selecting-draft-order-app-extension.png) ## Processing Scope and Draft Orders Your processing scope settings apply to draft orders: - **All orders** — All draft orders with bundles are processed - **Tagged only** — Only draft orders with matching tags are processed (you must tag the draft order before or at creation time) - **Exclude tags** — Draft orders with excluded tags are skipped ## Wholesale Discount Codes on Draft Orders If you apply a discount code to a draft order: - BundlesIQ detects the applied discount - The discount is factored into the component price calculations - In Hybrid and Operational modes, both the bundle discount and the wholesale discount are reflected in the component line prices - In Parent-Only (BOM) mode, the discount stays on the bundle line as-is (no component lines are added) **Example with a 50% wholesale discount:** ``` Bundle retail: $100.00 50% discount applied: $50.00 order total After transformation (Hybrid mode): Bundle line: $0.00 Component A: $60 retail → 20% bundle discount → 50% promo = $24.00 Component B: $40 retail → 20% bundle discount → 50% promo = $16.00 (Prices reflect combined bundle allocation + wholesale discount) Total: $50.00 ``` ## 3PL Protection on Draft Orders 3PL protection tags (`BIQ_PROCESSING`, `BIQ_READY`) are applied to draft orders the same way as standard orders. However, since draft orders are not typically sent to 3PLs until they are completed and converted to real orders, the tags serve primarily as status indicators. ## Reverting a Draft Order Transformation Unlike regular orders, draft orders can be **reverted** — meaning the bundle transformation is undone and the draft order is restored to its pre-BundlesIQ state. ### When to Revert - The customer changed their mind and you need to modify the draft before completing it - The bundle configuration was wrong and you need to start over - You want to test a different handling mode or pricing strategy ### How to Revert ![Bundle Tools dialog for draft orders — Reprocess, Revert & Reprocess, and Revert Only options](/assets/docs/images/bundlesiq/draft-order-app-extension.png) 1. **Open** the draft order in Shopify Admin 2. **Click** the **Bundle Tools** action (in the "More actions" menu) 3. **Choose** one of: - **Revert Only** — Undoes the transformation and leaves the draft in its original state. A `BIQ_REVERTED` tag is applied to prevent automatic re-transformation - **Revert & Reprocess** — Undoes the transformation and immediately re-runs processing from scratch ### What Reverting Does - **Removes** all BundlesIQ-created component line items and adjustment lines - **Restores** ghost SKU lines that were removed in Operational mode (re-adds the variant with original quantity) - **Removes** the "Bundle transformation" discount from Hybrid mode bundle lines (restoring them to their original price) - **Preserves** all non-bundle line items untouched > Reverting is only available for draft orders that have not been completed (converted to a regular order). Once a draft order is completed, the resulting regular order cannot be reverted. ## Common Mistakes - **Forgetting to enable draft order processing** — If "Process draft orders" is disabled in settings, BundlesIQ will not touch draft orders - **Editing a draft after processing and expecting no re-processing** — If you add or change line items, BundlesIQ may re-process when the `draft_orders/update` webhook fires. This is generally safe (idempotent), but be aware of it - **Completing a draft order that was not processed** — If BundlesIQ did not process the draft (due to settings or an error), completing it creates a standard order with only the ghost SKU. BundlesIQ will then attempt to process it as a standard order ## Troubleshooting | Issue | Possible Cause | Solution | |-------|---------------|----------| | Draft order was not transformed | "Process draft orders" is disabled | Enable it in Settings | | Draft order was not transformed | Processing scope is set to "Tagged only" and the draft does not have the required tag | Add the required tag to the draft order | | Components were added but prices look wrong | A discount code on the draft is interacting with bundle pricing | Review the price allocation and check if the combined discount makes sense | | Draft was processed but then reverted | The draft was updated after processing, triggering a re-evaluation | Check the BundlesIQ Health dashboard for processing logs | ## Related Pages - [How Orders Look in Each Mode](/documentation/bundlesiq/order-representation) - [Global Settings Overview](/documentation/bundlesiq/global-settings) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) --- ### Refunds & Returns # Refunds and Returns This guide explains how refunds and returns work for orders that have been processed by BundlesIQ, and what to expect in each handling mode. ## What You Will Accomplish You will understand how to handle refunds and returns for bundle orders, including partial refunds, and what each handling mode means for the refund workflow. ## How Refunds Work After Bundle Processing After BundlesIQ transforms an order, the order contains component line items (and possibly the bundle line, depending on your handling mode). Refunds are processed through Shopify's standard refund workflow, but the line items you refund depend on your handling mode. ## Refund Behavior by Handling Mode ### Parent-Only (BOM) Mode In Parent-Only mode, only the bundle line item exists on the order — there are no component line items. **To refund the full bundle:** 1. **Open** the order in Shopify Admin 2. **Click** **Refund** 3. **Select** the **bundle line item** and its full quantity 4. **Process** the refund **Inventory impact:** BundlesIQ automatically releases the reserved component inventory back to `available` when a Parent-Only order is refunded or cancelled. If the order was already fulfilled (reserved stock was consumed), BundlesIQ restocks the component quantities. **To refund a partial bundle (one component):** Partial component-level refunds are not directly supported in Parent-Only mode because components do not appear on the order. You can: - **Option A:** Refund a custom dollar amount from the bundle line using Shopify's manual refund feature - **Option B:** Refund the full bundle and re-create a new order with the adjusted items > Because Parent-Only mode does not add component line items to the order, inventory restocking for components is handled by BundlesIQ (not Shopify's built-in restock). Ensure BundlesIQ is active when processing refunds. --- ### Hybrid Mode In Hybrid mode, the bundle line is at $0 and components carry the prices. **To refund the full bundle:** 1. **Open** the order in Shopify Admin 2. **Click** **Refund** 3. **Select** all component line items and their full quantities 4. **Confirm** the refund amount matches the original bundle price 5. **Process** the refund **To refund a partial bundle (one component):** 1. **Select** only the specific component line item(s) to refund 2. **The refund amount** reflects the component's allocated price (not the full bundle price) > The $0 bundle label line does not need to be refunded since it has no value. ### Operational Mode In Operational mode, only priced component line items exist on the order. **To refund the full bundle:** 1. **Open** the order in Shopify Admin 2. **Click** **Refund** 3. **Select** all component line items that were part of the bundle 4. **Confirm** the total refund matches the original bundle price 5. **Process** the refund **To refund a partial bundle (one component):** 1. **Select** the specific component line item(s) 2. **The refund amount** reflects the component's allocated price > In Operational mode, there is no bundle line on the order. To identify which components belong to a bundle, check the order metafield `bundles_iq.transformation_audit` or the BundlesIQ Health dashboard. ### Reporting Mode In Reporting mode, the bundle line carries the full price and components are at $0. **To refund the full bundle:** 1. **Open** the order in Shopify Admin 2. **Click** **Refund** 3. **Select** the **bundle line item** and its full quantity 4. **The refund amount** is the bundle price 5. **Process** the refund **To refund a partial bundle (one component):** This is more complex in Reporting mode because components are at $0. You have two options: - **Option A:** Refund a custom amount by clicking **Refund** and manually entering the dollar amount for the component (based on its allocated value from the bundle) - **Option B:** Refund the full bundle and re-create a new order/draft with the remaining items > Partial refunds in Reporting mode require manual calculation because Shopify does not know the individual component values (they are all $0 on the order). ## Refund Summary by Mode | Action | Hybrid | Operational | Reporting | Parent-Only (BOM) | |--------|--------|-------------|-----------|-------------------| | **Full bundle refund** | Refund all component lines | Refund all component lines | Refund the bundle line | Refund the bundle line | | **Single component refund** | Refund the component at its allocated price | Refund the component at its allocated price | Manual amount entry required | Manual amount entry required | | **Inventory restock** | Shopify restocks the component variants | Shopify restocks the component variants | Shopify restocks the component variants + the bundle (ghost SKU) variant | BundlesIQ releases reserved or restocks consumed component inventory | | **Complexity** | Straightforward | Straightforward | More complex for partial refunds | Straightforward for full; manual for partial | ## Inventory Impact of Refunds When you process a refund in Shopify with the "Restock items" option: - **Component inventory** is restocked by Shopify based on the refunded component line items - **Bundle inventory** is recalculated by BundlesIQ when the component inventory webhook fires (if inventory sync is enabled) In **Reporting mode**, if you refund the bundle line item, Shopify restocks the ghost SKU variant. BundlesIQ's inventory sync will then set it back to the calculated availability on the next sync cycle. ## Returns Workflow For stores using Shopify's returns workflow: 1. **Create a return** from the order in Shopify Admin 2. **Select** the line items being returned (components in Hybrid/Operational, bundle line in Reporting) 3. **Process** the return and restock as appropriate 4. **Issue** a refund for the returned items The same mode-specific guidance applies: in Hybrid and Operational modes, you work with component line items. In Reporting and Parent-Only modes, you work with the bundle line item. ## Exchanges If a customer wants to exchange a bundle for a different bundle: 1. **Process** a return/refund for the original bundle order (following the mode-specific steps above) 2. **Create** a new order (or draft order) with the replacement bundle 3. BundlesIQ will process the new order automatically ## What to Expect After a Refund | After refund | Expected behavior | |-------------|------------------| | Component inventory | Restocked to the relevant location (if "Restock items" was selected) | | Bundle availability | Recalculated by BundlesIQ based on updated component stock | | Order status | Shows as "Partially refunded" or "Refunded" in Shopify Admin | | BundlesIQ processing | No re-processing occurs — the original transformation is preserved | ## Common Mistakes - **Refunding the $0 bundle line in Hybrid mode** — This has no financial effect since it is $0. Refund the component lines instead - **Not restocking components in Reporting mode** — When you refund the bundle line, make sure to also restock the component variants (which are listed at $0 but still represent physical inventory) - **Assuming BundlesIQ re-processes after a refund** — BundlesIQ does not modify orders during refunds. Refunds follow Shopify's standard flow on the already-transformed order ## Troubleshooting | Issue | Possible Cause | Solution | |-------|---------------|----------| | Refund amount does not match expected bundle price | Rounding in price allocation caused small differences | The total refund of all components should be within a few cents of the bundle price. Adjust manually if needed | | Cannot refund individual component in Reporting mode | Components are at $0 | Use Shopify's manual refund amount feature to enter the component's value | | Bundle inventory did not update after refund | Inventory sync is disabled, or the component restock did not trigger a webhook | Manually check component inventory levels. Enable inventory sync if it is disabled | ## Related Pages - [How Orders Look in Each Mode](/documentation/bundlesiq/order-representation) - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Inventory Rules](/documentation/bundlesiq/inventory-rules) --- ### 3PL Integration # 3PL Integration Guide BundlesIQ includes built-in protection to prevent third-party logistics providers (3PLs) and warehouse management systems (WMS) from importing orders before bundle processing completes. This guide explains how to configure and use these features. ## What You Will Accomplish You will set up 3PL protection so your fulfillment partner never acts on an order before BundlesIQ has finished transforming it. ## When to Use This Guide - You use a 3PL or WMS that automatically imports orders from Shopify - You want to prevent your warehouse from picking the ghost SKU instead of the real components - You need to configure tag-based filtering in your 3PL system ## The Race Condition Problem Without protection, this failure mode can occur: 1. Customer places an order containing the bundle ghost SKU 2. Your 3PL imports the order immediately (or within seconds) 3. Warehouse staff starts picking based on the ghost SKU (wrong item) 4. BundlesIQ completes the transformation, but it is too late — the wrong items are already being packed BundlesIQ prevents this with a **"default deny"** approach: orders are not eligible for fulfillment until BundlesIQ explicitly marks them as ready. ## Protection Mechanisms BundlesIQ uses a "belt and suspenders" approach with two layers of protection: ### Layer 1: Tag-Based Gating (Primary) BundlesIQ applies tags to orders at each stage of processing: | Tag | When Applied | Meaning | |-----|-------------|---------| | `BIQ_PROCESSING` | Immediately when BundlesIQ begins processing | Order is being transformed — do not import | | `BIQ_READY` | After successful transformation | Order is safe to import and fulfill | | `BIQ_ERROR` | When processing fails | Order has an issue — do not import until resolved | | `BIQ_REVERTED` | After a draft order transformation is reverted | Draft order has been restored to pre-transformation state (draft orders only) | **Recommended 3PL configuration:** Configure your 3PL to **only import orders that have the `BIQ_READY` tag**. This is the most reliable approach because orders without the tag are simply invisible to the 3PL. ### Layer 2: Shopify Fulfillment Holds (Backstop) BundlesIQ optionally places a Shopify-native fulfillment hold on orders during processing. This is a system-level hold that appears in the Shopify Admin as "On hold" and is respected by many fulfillment integrations. - The hold is placed after the order is created (note: there may be a brief delay as Shopify creates fulfillment orders) - The hold is released after BundlesIQ successfully completes transformation - If processing fails, the hold remains in place ### Optional: Alias Tags If your 3PL expects specific tag names, you can configure alias tags: | Setting | Default | Purpose | |---------|---------|---------| | **Hold alias tag** | `ON-HOLD` | Applied during processing (same timing as `BIQ_PROCESSING`) | | **Ready alias tag** | `READY_TO_SHIP` | Applied after successful processing (same timing as `BIQ_READY`) | Alias tags are applied in addition to the standard BIQ tags, not instead of them. ## Setting Up 3PL Protection ### Step 1: Enable Protection in BundlesIQ 1. **Navigate** to **BundlesIQ > Settings** 2. **Under** **3PL Protection**, ensure the master toggle is **Enabled** 3. **Configure** tag names if you need custom values (the defaults work for most setups) 4. **Enable** alias tags if your 3PL expects specific tag names like `ON-HOLD` or `READY_TO_SHIP` 5. **Enable** fulfillment holds if you want the Shopify-native hold as a backstop 6. **Click** **Save** ### Step 2: Configure Your 3PL Configure your 3PL or WMS to filter orders based on BundlesIQ tags. The exact steps depend on your system. Choose one of the three integration patterns below: #### Pattern A (Recommended): Allowlist on `BIQ_READY` Configure your OMS/WMS/3PL to **only import orders containing `BIQ_READY`** (or your ready alias tag). - **Pros:** Zero race window — very hard to ship an unprocessed order - **Cons:** Non-bundle orders may need a separate rule to add the ready tag (see [Orders Without Bundles](#orders-without-bundles)) #### Pattern B: Denylist on Processing / Error Tags Configure your OMS/WMS/3PL to skip orders containing `BIQ_PROCESSING` or `BIQ_ERROR`. - **Pros:** Non-bundle orders flow normally without extra work - **Cons:** Small race window exists in systems that import instantly before tags appear. Enabling fulfillment holds reduces the impact #### Pattern C (Backstop Only): Rely on Fulfillment Holds Use this only when the external system cannot filter by tags. - **Pros:** Minimal configuration in the downstream system - **Cons:** Does not always stop label creation in every tool — better as a safety net, not the primary control ### Common 3PL Configuration Examples **ShipStation:** - Map Shopify order tags to a ShipStation custom field - Create a "BundlesIQ Ready" saved view that only shows orders where the custom field contains `BIQ_READY` - Train staff to work exclusively from the "BundlesIQ Ready" view - See the dedicated [ShipStation Setup](/documentation/bundlesiq/shipstation-setup) guide for detailed step-by-step instructions **Easyship:** - Use "Exclude orders by tag" to exclude `BIQ_PROCESSING` and `BIQ_ERROR` - Orders become visible to Easyship after BundlesIQ switches them to `BIQ_READY` **ShipHero:** - Use the ShipHero setting to control how Shopify fulfillment holds are imported - Optionally use Shopify order tags inside ShipHero for batching and routing **Extensiv (formerly 3PL Central / Skubana):** - Use Shopify "Filter Order Rules" to only load orders that match your ready state tags - Or use the "Hold Order By Tags" pattern (don't load orders until the processing tag is removed) **Shippo:** - If tag-based filtering is required, confirm whether Shippo can filter based on Shopify order tags in your setup - Otherwise, rely on the `BIQ_READY` workflow discipline combined with the Shopify fulfillment hold backstop **Other 3PLs:** - Check your 3PL's documentation for Shopify tag filtering capabilities - If your 3PL supports Shopify fulfillment status filtering, the fulfillment hold provides an additional safety net ### Step 3: Test the Protection Run through this quick verification test before going live: 1. **Place** a test order containing a bundle product 2. **Check** your 3PL system immediately — depending on your integration pattern: - **Allowlist (Pattern A):** The order should not appear at all (no `BIQ_READY` tag yet) - **Denylist (Pattern B):** The order should be clearly marked as not-ready - **Backstop (Pattern C):** The order should be blocked by a fulfillment hold 3. **Wait** a few seconds for BundlesIQ to process 4. **Check** again — the order should now have the `BIQ_READY` tag and be importable 5. **Verify** the imported order shows the correct component line items (post-transformation state) 6. **Test an error scenario** — intentionally misconfigure a bundle to trigger a processing failure and confirm: - `BIQ_ERROR` appears on the order - The fulfillment hold remains in place (if enabled) - The order does **not** become ship-ready in your downstream system ## Compatibility Checklist for Any OMS/WMS/3PL When evaluating whether a system works with BundlesIQ, answer these four questions: 1. **Tag filtering:** Can it include or exclude Shopify orders based on order tags at import? 2. **Tag visibility:** Does it import Shopify order tags at all? 3. **Hold handling:** Does it delay importing orders that have a Shopify fulfillment hold? 4. **Fulfillment sync:** Does it create fulfillments in Shopify or push tracking back to Shopify? If you have (1) or (3), you can implement a robust "default deny" workflow. If you only have (2), you can still use a manual workflow where staff checks tags before shipping. ## Tag Naming Best Practices - Use **ASCII, uppercase, underscore or hyphen** format: `BIQ_READY`, `ON-HOLD` - Avoid special characters that some systems handle inconsistently: `:` `/` `@` emoji - Keep tags short and stable — 3PL rule builders often require exact matches - Document your tag conventions and share them with your fulfillment team ## What Happens When Processing Fails If BundlesIQ cannot process an order: 1. The `BIQ_PROCESSING` tag remains (or is replaced with `BIQ_ERROR`) 2. The `BIQ_READY` tag is **not** applied 3. Fulfillment holds remain in place 4. The order is **not** importable by the 3PL 5. The error appears in the BundlesIQ **Health** dashboard 6. If automatic retries are enabled, BundlesIQ will attempt to reprocess after the cooldown period 7. Once resolved (automatically or manually), the `BIQ_READY` tag is applied and the order becomes importable ## Parent-Only (BOM) Mode and 3PL If you use **Parent-Only (BOM)** mode, your 3PL will see only the bundle ghost SKU on the order — no component line items are added. This means: - Your 3PL or warehouse must know the bill of materials (BOM) for each bundle SKU - 3PL protection tags (`BIQ_PROCESSING`, `BIQ_READY`) still apply — they gate inventory reservation processing, not order editing - Fulfillment holds are still placed and released during processing > Parent-Only mode is typically used with **internal warehouses** or **assembly operations** where staff have access to the BOM, not with external 3PLs that expect individual SKUs on each order. If your 3PL needs to see component line items, use Hybrid, Reporting, or Operational mode instead. ## Orders Without Bundles If an order does not contain any bundle products: - BundlesIQ does not apply any tags to the order - The order is immediately available to your 3PL through its normal import process - No fulfillment holds are placed > If your 3PL is configured to **only** import orders with the `BIQ_READY` tag, non-bundle orders will not be imported either. In this case, you may want to use a Shopify Flow or script to add the `BIQ_READY` tag to non-bundle orders automatically. Alternatively, configure your 3PL to import orders that **either** have `BIQ_READY` **or** do not have `BIQ_PROCESSING`. ## Common Mistakes - **Not configuring the 3PL side** — Enabling 3PL protection in BundlesIQ only adds tags. You must also configure your 3PL to filter on those tags - **Using denylist instead of allowlist** — The denylist approach has a small race window (order created before tag is applied). The allowlist approach (`BIQ_READY` required) is more reliable - **Forgetting about non-bundle orders** — If your 3PL requires the `BIQ_READY` tag, make sure non-bundle orders also get tagged or use a combined filter rule ## Related Pages - [How BundlesIQ Works](/documentation/bundlesiq/how-bundlesiq-works) - [Global Settings Overview](/documentation/bundlesiq/global-settings) - [ShipStation Setup](/documentation/bundlesiq/shipstation-setup) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) --- ### Channels # Supported Channels and Compatibility BundlesIQ is a **post-checkout** bundle engine. It does not change the checkout experience. Instead, it transforms **orders and draft orders after they are created**. This page explains what that means across Shopify channels, where it’s “works by design,” and where it becomes **connector-dependent**. --- ## What “Supported” Means in BundlesIQ BundlesIQ can process any transaction that meets all of the following: 1. It results in a **Shopify Order** or **Shopify Draft Order** (visible in Shopify Admin), and 2. The record is **eligible for post-checkout edits**, and 3. The order contains a BundlesIQ **bundle variant (ghost SKU variant)**, and 4. No third-party system immediately **locks, rewrites, or rejects** post-checkout changes. > Practical rule of thumb: **If it shows up as an order/draft order in Shopify Admin, BundlesIQ can usually process it.** > The main exceptions are third-party marketplace/connector workflows that re-sync or constrain edits. --- ## Compatibility Levels To avoid overpromising, channels are described using these levels: - **Works by design**: The channel creates standard Shopify Orders/Draft Orders and typically doesn’t interfere with post-checkout edits. - **Works, but has channel UX limitations**: BundlesIQ can transform the resulting Shopify order, but the channel UI (receipt, confirmation, etc.) may show the ghost SKU before transformation. - **Conditional (connector-dependent)**: The order may be created in Shopify, but a connector/marketplace may re-sync, lock, or override edits. Requires testing. - **Not applicable**: BundlesIQ does not transform at checkout time (no cart/checkout transformation). --- ## Channel Compatibility | Channel / Source | Compatibility | What to expect | |---|---|---| | **Online Store** | Works by design | The most common case. Customers purchase the ghost SKU variant; BundlesIQ transforms after the order is created. | | **Draft Orders** | Works by design | Fully supported. Common for B2B and wholesale workflows. | | **Shopify B2B** | Works by design | Supported as long as the flow creates standard Orders/Draft Orders. Test if your B2B setup uses specialized integrations. | | **Shop App** | Works by design | Produces standard Shopify orders; BundlesIQ processes post-checkout. | | **Buy Button** | Works by design | Produces standard Shopify orders; BundlesIQ processes post-checkout. | | **Headless / Hydrogen / Storefront API** | Works by design | Supported as long as checkout completion results in standard Shopify orders. | | **Facebook / Instagram (Meta)** | Conditional (connector-dependent) | Often works, but some channel/connector setups may re-sync inventory or order data. Test before relying on it. | | **Google Shopping** | Conditional (connector-dependent) | Often works, but connector behavior varies. Test before going live. | | **TikTok Shop** | Conditional (connector-dependent) | Frequently connector-dependent. Some setups have strict fulfillment/inventory expectations that can conflict with post-checkout edits. Test. | | **Amazon / eBay (via marketplace connectors)** | Conditional (connector-dependent) | If the connector creates Shopify orders, BundlesIQ can process them — but some connectors overwrite edits after sync. Test with your specific connector. | | **Shopify POS** | Works, but has channel UX limitations | BundlesIQ can transform the resulting order after sale completion, but POS UI/receipt typically reflects the pre-transformation ghost SKU. BundlesIQ does **not** provide a POS extension yet. | --- ## Important: Post-Checkout Processing (What BundlesIQ Does and Doesn’t Do) BundlesIQ transforms: - **Orders** using Shopify’s post-checkout order editing capabilities - **Draft orders** using draft-order updates BundlesIQ does **not**: - Transform bundles at checkout time - Provide a POS-specific component-scanning interface (yet) **Implications:** - **Order confirmation emails** typically send before BundlesIQ completes transformation, so customers may see the ghost SKU in the initial email. - Channel UIs that print or display receipts at time-of-sale (like POS) will typically show the ghost SKU, not the expanded components. --- ## Why Parent-Only (BOM) Mode Is the Safest Multi-Channel Option If you sell through connectors/marketplaces that may resist post-checkout edits, **Parent-Only (BOM)** has a unique advantage: - Parent-Only mode does **not** expand the order into component line items - That means there is no risk of line-item re-sync conflicts or “connector overwrote my edits” - Inventory/cost behavior can still be managed via BundlesIQ settings (depending on your workflow) > Parent-Only is often the best fit when you need cross-channel consistency and want to minimize risk from connector behavior. --- ## Subscription Apps (Recharge, Skio, Bold, etc.) BundlesIQ can process subscription orders when those orders appear as standard Shopify orders or draft orders. Because subscription apps vary, consider them **works by design** with a simple requirement: - **Test at least one subscription checkout and one renewal flow**, and confirm: - Order still transforms after the subscription app finishes its own updates - Line item properties (if used) are preserved - Renewals continue to transform reliably --- ## POS-Specific Notes BundlesIQ works **after** the POS sale is completed and the order exists in Shopify. What BundlesIQ **can** do: - Transform the Shopify order created by POS (post-sale) - Keep Shopify Admin accurate for ops/accounting What BundlesIQ **does not** do today: - Show components inside the POS cart before checkout - Provide POS staff a “bundle breakdown” UI within POS - Change the printed receipt to show components If POS staff need to see component breakdown before completing the sale, recommend one of: - Staff reference the bundle configuration in BundlesIQ, or - Use Parent-Only mode for POS-heavy workflows, or - Treat POS component visibility as a future enhancement (POS extension) --- ## How to Validate a Channel Before Going Live If you rely on a non-core channel (marketplaces/connectors), run a quick validation: 1. Place an order through the target channel 2. Confirm BundlesIQ detected the bundle and processed successfully (Health dashboard) 3. Confirm the transformed order in Shopify Admin matches your handling mode expectations 4. If you use fulfillment automation/3PL: - Confirm holds/tags behave correctly - Confirm the external system imports only after processing 5. If you use inventory sync on the ghost SKU: - Confirm availability behaves correctly across channels --- ## Known Limitations | Limitation | Detail | |---|---| | No checkout-time transformation | BundlesIQ expands bundles after order creation, not during checkout. | | Confirmation emails may show ghost SKU | Processing occurs after order creation; initial emails/receipts may reflect pre-transform content. | | Connector conflicts possible | Some marketplaces/connectors re-sync or overwrite order edits. Test your exact setup. | | No channel-specific handling mode | Handling mode is global or per bundle, not per channel. | --- ## Related Pages - [How BundlesIQ Works](/documentation/bundlesiq/how-bundlesiq-works) - [Draft Orders and B2B](/documentation/bundlesiq/draft-orders) - [Troubleshooting](/documentation/bundlesiq/troubleshooting) --- ### ShipStation Setup # ShipStation Setup This guide explains how to configure ShipStation so your team never creates labels based on a pre-transformation bundle order. BundlesIQ protects ShipStation workflows using: - Shopify order tags (`BIQ_PROCESSING`, `BIQ_READY`, `BIQ_ERROR`) - (Optional) Shopify fulfillment holds as a backstop --- ## What You Will Accomplish - Import Shopify order tags into ShipStation - Create a "BundlesIQ Ready" view to ship from - Optionally add automation rules to make non-ready orders highly visible --- ## Prerequisites - Your Shopify store is connected to ShipStation - BundlesIQ 3PL Protection is enabled (default tags are fine) - You know which tag represents "ready" (default: `BIQ_READY`) --- ## Step 1: Import Shopify Order Tags into ShipStation ShipStation can map Shopify order tags into one of its custom fields. 1. In ShipStation, go to **Settings** 2. Go to **Selling Channels > Store Setup** 3. Edit your Shopify store connection 4. Map **Shopify Order Tags** to **Custom Field 1** (or 2/3) 5. Save --- ## Step 2: Create Saved Views for BundlesIQ States Your goal is to make "Ready" orders the only place staff works from. Create these saved views (filters): ### View A: "BundlesIQ Ready" - Store: your Shopify store - **Custom Field 1 contains** `BIQ_READY` ### View B: "BundlesIQ Processing" - Store: your Shopify store - **Custom Field 1 contains** `BIQ_PROCESSING` ### View C: "BundlesIQ Error" - Store: your Shopify store - **Custom Field 1 contains** `BIQ_ERROR` Recommended workflow: - Only create labels from **BundlesIQ Ready** - Treat **Processing** as "wait" - Treat **Error** as "do not ship" until resolved --- ## Step 3: Warehouse Workflow (What to Tell Your Team) 1. Work exclusively from the **BundlesIQ Ready** view 2. If an order is not in "Ready," do not ship it yet 3. If an order appears in **BundlesIQ Error**: - Do not ship - Resolve the issue in BundlesIQ / Shopify - After resolution, the order should move into "Ready" (depending on your refresh cadence) --- ## Optional: Add ShipStation Automation Rules (Visual Warnings) Automation rules can help you flag orders that aren't ready, but they are not a replacement for the "ship only from Ready view" workflow. Example rules: - IF Custom Field 1 contains `BIQ_PROCESSING` - THEN add ShipStation tag: `BIQ_NOT_READY` - THEN add an internal note: "Waiting for BundlesIQ processing" - IF Custom Field 1 contains `BIQ_ERROR` - THEN create an alert: "BundlesIQ error — do not ship" **Important warnings:** - Avoid using "Don't Import the Order" rules unless you are 100% sure. It is permanent. - Automation rules generally run when an order imports / first enters certain statuses. If the order updates later, rules may not re-run automatically. --- ## Troubleshooting ### I don't see BIQ tags in ShipStation - Confirm the Shopify order in Admin has BIQ tags - Confirm your ShipStation store mapping is set to import Shopify order tags into a custom field - Refresh the store connection / reimport recent orders ### The order appears but still looks wrong (ghost SKU / old line items) - Wait a moment and refresh. If ShipStation imported the order during processing, it may not reflect the final state yet. - Confirm the order has `BIQ_READY` in Shopify before shipping. ### Orders are stuck in Processing or Error - Check BundlesIQ Health / logs - `BIQ_ERROR` means do not ship until fixed ## Related Pages - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) --- ### Wholesale Gorilla # Using Wholesale Gorilla with BundlesIQ Wholesale Gorilla and BundlesIQ can both adjust pricing on the same draft order lines. When they do, they can conflict — because Shopify only allows **one line-level discount structure per draft order line**. BundlesIQ uses line-level pricing adjustments to transform the bundle correctly. Wholesale Gorilla may also apply its wholesale pricing as line-level adjustments. If Wholesale Gorilla runs *after* BundlesIQ has already processed the draft order, it can overwrite the BundlesIQ bundle pricing and cause the draft order total to calculate incorrectly. ## The Safest Rule > Wholesale Gorilla should apply pricing **before** BundlesIQ processes the bundle — **or** BundlesIQ should be the only app responsible for pricing the bundle. The rest of this guide covers six concrete options for achieving that, followed by a recommended path. --- ## Option 1: Use a BundlesIQ Exclusion Tag **Best for:** Stores that want to keep automatic draft order processing enabled but need to temporarily prevent BundlesIQ from processing a specific draft order. In this setup, the draft order is created with a tag that tells BundlesIQ to skip processing. After Wholesale Gorilla pricing has been applied, the exclusion tag is removed so BundlesIQ can process the bundle. **Recommended workflow:** 1. In BundlesIQ, go to **Settings > App Preferences > Exclude Tags** 2. Add an exclusion tag, such as `BIQ_SKIP` 3. When creating the draft order, add the exclusion tag **before** the draft order is saved 4. Let Wholesale Gorilla apply its wholesale pricing 5. Confirm the Wholesale Gorilla pricing is visible and correct 6. Remove the exclusion tag from the draft order 7. Save the draft order so BundlesIQ can process the bundle > **Test this first.** Some Wholesale Gorilla draft order workflows may not work correctly if tags are added before wholesale pricing is applied. Verify the flow on a test order before relying on it operationally. --- ## Option 2: Let Wholesale Gorilla Price the Draft, Then Let BundlesIQ Process After the Draft Becomes an Order **Best for:** Stores that need Wholesale Gorilla to handle draft order pricing first and do not need BundlesIQ to transform the bundle while the order is still in draft status. In this setup, BundlesIQ draft order processing is turned off, so BundlesIQ will not process bundles while the order is still a draft. Wholesale Gorilla prices the draft order first. Once the draft is converted into a regular Shopify order, BundlesIQ processes the bundle at the order stage. **Recommended workflow:** 1. Turn off draft order processing in BundlesIQ 2. Create the draft order in Shopify 3. Add the wholesale customer to the draft order 4. Apply Wholesale Gorilla pricing to the draft order 5. Confirm the Wholesale Gorilla pricing is visible and correct 6. Complete or convert the draft order into a Shopify order 7. BundlesIQ processes the bundle after the Shopify order is created > This does **not** manually process the draft order in BundlesIQ. Turning off draft order processing prevents BundlesIQ from processing drafts entirely — processing happens later, after the draft becomes an order. This option is a good fit when the draft order needs to show the correct wholesale price, but the final fulfillment/order structure can be handled after order creation. --- ## Option 3: Price the Bundle Directly in BundlesIQ **Best for:** Bundles that are primarily or only sold in B2B / wholesale scenarios. In this setup, BundlesIQ owns the bundle pricing instead of Wholesale Gorilla. **Recommended workflow:** 1. Add the wholesale discount directly to the bundle configuration inside BundlesIQ 2. Make sure the bundle parent product is **not** also being discounted by Wholesale Gorilla 3. If possible, make sure the bundle components are **not** eligible for additional Wholesale Gorilla discounting after BundlesIQ processes the bundle 4. When the draft order or order is created, BundlesIQ applies the correct wholesale bundle pricing during the bundle transformation This is usually the cleanest technical option, because only one app is responsible for pricing the bundle. --- ## Option 4: Use Operational Handling Mode **Best for:** Stores that care more about fulfillment accuracy than preserving the bundle parent line and bundle-level attribution. In [Operational mode](/documentation/bundlesiq/handling-modes), BundlesIQ replaces the bundle parent item with its component items. **Recommended workflow:** 1. Configure the bundle in BundlesIQ 2. Set the bundle handling mode to **Operational** 3. Do **not** apply a separate bundle-level wholesale discount in BundlesIQ 4. Let BundlesIQ replace the bundle with its components 5. Let Wholesale Gorilla price the component products the same way it normally prices other wholesale products This option is useful when the merchant mainly needs the order to contain the correct component SKUs for fulfillment and is comfortable with the final pricing being based on the Wholesale Gorilla pricing for the component products. > This is **not** the best option if the merchant needs to preserve a specific bundle-level price or bundle-level discount. --- ## Option 5: Use a Shopify Order-Level Discount Instead of Re-Applying Wholesale Gorilla After BundlesIQ **Best for:** Cases where the customer needs an additional discount *after* BundlesIQ has already processed the bundle. If a discount needs to be applied after BundlesIQ runs, the safest option is to use a Shopify order-level discount rather than another line-level repricing step. **Recommended workflow:** 1. Let BundlesIQ process the bundle 2. Apply a Shopify **order-level** discount to the draft order 3. Do **not** re-apply Wholesale Gorilla line-level pricing after BundlesIQ has processed the bundle This is safer because BundlesIQ needs to preserve its line-level bundle pricing adjustments, while an order-level discount is separate from the individual bundle line adjustments. --- ## Option 6: Adjust Wholesale Gorilla Price Rules So Bundle Products Are Not Included **Best for:** Stores using broad Wholesale Gorilla pricing rules that unintentionally include bundle products. If Wholesale Gorilla uses broad or storewide wholesale rules, bundle products may be included automatically. That makes it difficult to keep Wholesale Gorilla from repricing and overwriting bundle lines. **Recommended workflow:** 1. Review the Wholesale Gorilla pricing rules 2. Avoid using storewide wholesale rules if bundle products need different handling 3. Use product-, variant-, or collection-level Wholesale Gorilla rules instead 4. Keep bundle parent products outside of Wholesale Gorilla's discount scope where possible 5. Let BundlesIQ own the pricing for bundle products This option helps prevent Wholesale Gorilla from unintentionally repricing bundle lines that BundlesIQ has already adjusted. --- ## Recommended Path For the most reliable setup, we recommend one of these approaches: 1. **Let Wholesale Gorilla price the draft, then let BundlesIQ process after the exclusion tag is removed** (Option 1) 2. **Let BundlesIQ own the wholesale bundle price** (Option 3) 3. **Use a Shopify order-level discount after BundlesIQ** (Option 5) ### The Workflow to Avoid > BundlesIQ processes the draft order first, then Wholesale Gorilla applies line-level pricing afterward. That sequence can overwrite the BundlesIQ bundle pricing and cause the draft order total to calculate incorrectly. ## Related Pages - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [Draft Orders](/documentation/bundlesiq/draft-orders) - [Troubleshooting](/documentation/bundlesiq/troubleshooting) --- ### Troubleshooting # Troubleshooting, FAQ, and Expected Behavior Guide This guide covers three categories of questions about BundlesIQ: 1. **Expected behavior** — Your order looks different than expected, but BundlesIQ is working correctly based on your handling mode. Start with [Section 1](#1-understanding-expected-behavior-by-handling-mode) if your order "looks wrong" but processing succeeded. 2. **Error diagnosis** — Something went wrong during processing. See [Section 2](#2-diagnosing-processing-failures) for the checklist and [Section 3](#3-specific-error-deep-dives) for detailed error resolution. 3. **FAQ and procedures** — Common questions about processing, pricing, inventory, and operational tasks. See [Section 4](#4-pricing-and-reporting-troubleshooting) through [Section 7](#7-frequently-asked-questions). --- ## 1. Understanding Expected Behavior by Handling Mode BundlesIQ transforms orders differently depending on your handling mode. Before troubleshooting, confirm that what you see is not the intended behavior of your chosen mode. ### 1.1 Quick Reference: What Each Mode Does to Your Order | Handling Mode | Bundle Line Item | Component Line Items | Revenue Attributed To | Best For | |--------------|-----------------|---------------------|----------------------|----------| | **Hybrid** | Stays at **$0.00** | Added with **allocated prices** | Component SKUs | B2B, wholesale | | **Reporting** | Stays at **original price** | Added at **$0.00** each | Bundle (ghost) SKU | DTC, B2C | | **Operational** | **Removed** (qty set to 0) | Added with **allocated prices** | Component SKUs | Distribution, 3PL | | **Parent-Only (BOM)** | Stays at **original price** | **Not added** to the order | Bundle (ghost) SKU | Made-to-order, kitting | In all four modes, the order total remains unchanged from what the customer paid at checkout. > **To check your mode:** Open the bundle in **BundlesIQ > Bundles** and look at the **Handling Mode** field. If it says "Use store default," check **BundlesIQ > Settings > Default Handling Mode**. --- ### 1.2 Why Did BundlesIQ Remove the Bundle From My Order? **Short answer:** You are using **Operational mode**. Removing the bundle line item is the correct, expected behavior. In Operational mode, BundlesIQ sets the bundle (ghost SKU) quantity to zero and adds the individual component SKUs with their allocated prices. The order total remains unchanged. This is designed for warehouses, distributors, and 3PLs that require strict SKU-level accuracy — no bundle abstraction left behind. **Example — before processing:** ``` Summer Essentials Bundle (x1) $99.00 ``` **After Operational mode processing:** ``` Sunglasses (x1) $41.25 Beach Towel (x1) $33.00 Sunscreen (x1) $24.75 Total $99.00 ``` The bundle line is gone. Only the real, fulfillable SKUs remain. **If you do not want the bundle removed**, switch to one of these modes: - **Hybrid mode** — Bundle stays on the order at $0, components are added with allocated prices. Good for B2B and wholesale. - **Reporting mode** — Bundle stays at its original price, components are added at $0. Good for DTC and clean revenue reporting. - **Parent-Only (BOM) mode** — Bundle stays at its original price, no component lines are added. Good for made-to-order and kitting workflows. See [Handling Modes Explained](/documentation/bundlesiq/handling-modes) for a full comparison. > **Mode changes apply to new orders only.** Previously processed orders are not retroactively modified. See [Section 1.7](#17-i-changed-my-handling-mode-but-old-orders-did-not-change). --- ### 1.3 Why Are My Components Showing at $0? **Short answer:** You are using **Reporting mode**. Components at $0 is the correct, expected behavior. In Reporting mode, the bundle line item keeps its original price ($99.00 in the example), and individual components are added at $0.00 each. This keeps revenue attributed to the bundle SKU, which is ideal for DTC brands that want clean Shopify Analytics and customer-friendly order views. **Example — after Reporting mode processing:** ``` Summer Essentials Bundle (x1) $99.00 Sunglasses (x1) $0.00 Beach Towel (x1) $0.00 Sunscreen (x1) $0.00 Total $99.00 ``` **If you need priced component lines**, switch to **Hybrid mode** or **Operational mode**. > **3PL note:** Some 3PLs expect all line items to have prices for customs declarations. If your 3PL reports issues with $0 component lines, consider Hybrid mode instead. --- ### 1.4 Why Is the Bundle Showing at $0 on the Order? **Short answer:** You are using **Hybrid mode**. The bundle at $0 is the correct, expected behavior. In Hybrid mode, the bundle line item is set to $0.00 and the component line items carry the allocated prices. This preserves both what was purchased (the bundle line) and what needs to be fulfilled (the components with prices), making it ideal for B2B and wholesale. **Example — after Hybrid mode processing:** ``` Summer Essentials Bundle (x1) $0.00 Sunglasses (x1) $41.25 Beach Towel (x1) $33.00 Sunscreen (x1) $24.75 Total $99.00 ``` **If you want the bundle to keep its original price**, switch to **Reporting mode** or **Parent-Only (BOM) mode**. --- ### 1.5 Why Were No Component Lines Added to My Order? **Short answer:** You are most likely using **Parent-Only (BOM) mode**. No component lines on the order is the correct, expected behavior. In Parent-Only mode, the bundle stays on the order exactly as placed — no line items are added, no prices are changed. BundlesIQ manages component inventory behind the scenes by reserving, consuming, and restocking component stock automatically. **Example — after Parent-Only mode processing:** ``` Summer Essentials Bundle (x1) $99.00 Total $99.00 (No component line items on the order. Component inventory is reserved, consumed, and restocked behind the scenes.) ``` **How to verify processing succeeded:** 1. Check the **BundlesIQ Health dashboard** — the order should show status **Processed** 2. Check for the `BIQ_READY` order tag in Shopify Admin 3. Check the component products' inventory — `reserved` quantities should have increased **If you expected component lines to appear**, verify: - Your handling mode is not set to Parent-Only (check both the bundle and store default) - If the mode is correct but components still did not appear, see [Section 2.1](#21-bundle-did-not-process--components-did-not-appear) for processing failure diagnosis --- ### 1.6 What Does the Customer See After Checkout? The customer's checkout experience is identical in all four modes — they purchase the bundle product at its listed price. The transformation happens **after** checkout, so timing matters: | Touchpoint | What the Customer Sees | |-----------|----------------------| | **Checkout** | The original bundle product at the bundle price (transformation has not happened yet) | | **Order confirmation email** | Usually the **original** bundle product — the email is sent before transformation completes in most cases | | **Order status page** | The **transformed** order (if they check after processing completes, typically 2-15 seconds) | | **Account order history** | The **transformed** order | **Key insight:** The order confirmation email almost always shows the pre-transformation order because Shopify sends the email immediately after order creation, before BundlesIQ receives the webhook and processes it. > **If customer-facing order clarity is important**, use **Reporting mode** or **Parent-Only mode** — these preserve the most familiar order view for the customer, since the bundle name and price remain visible even after transformation. --- ### 1.7 I Changed My Handling Mode but Old Orders Did Not Change **This is expected.** Handling mode changes apply to **new orders only**. Previously processed orders are not retroactively modified. **Why:** BundlesIQ uses the Shopify Order Edit API, which creates audit-tracked changes. Retroactively re-transforming orders would generate new order edit entries, potentially confuse accounting, and risk data integrity for orders that may already be fulfilled or partially fulfilled. **What you can do:** - **For future orders:** The new mode takes effect immediately for orders placed after the change - **For specific past orders (draft orders only):** Use the [Revert & Reprocess](#63-reprocessing-and-reverting-orders) tool to re-transform individual draft orders under the new mode - **For fulfilled orders:** These cannot be re-transformed. Adjust reporting manually if needed - **For unfulfilled regular orders:** These cannot be reverted (Shopify Order Edit API limitation), but you can reprocess them if the original transformation failed --- ## 2. Diagnosing Processing Failures ### 2.1 Bundle Did Not Process / Components Did Not Appear **Symptoms:** You placed an order containing a bundle product, but the order still shows only the ghost SKU without component line items. > **Parent-Only (BOM) mode:** If your bundle uses Parent-Only mode, this is expected behavior. In Parent-Only mode, no component line items are added to the order. The bundle line stays as-is and component inventory is managed behind the scenes. Check the BundlesIQ Health dashboard to confirm the order was processed successfully, and verify that component `reserved` quantities increased. See [Section 1.5](#15-why-were-no-component-lines-added-to-my-order). **Check these in order:** 1. **Is the bundle Active?** - Open the bundle in **BundlesIQ > Bundles** and verify the status is **Active** (not Draft, Inactive, or Archived) 2. **Is order processing enabled?** - Go to **BundlesIQ > Settings** and verify **Process orders** is enabled (or **Process draft orders** if it was a draft order) 3. **Does the processing scope include this order?** - If your processing scope is set to "Tagged only," verify the order has the required tag - If you have exclude tags configured, verify the order does not have an excluded tag 4. **Was the webhook received?** - Check the **BundlesIQ > Health** dashboard for the order. If the order does not appear at all, Shopify may not have delivered the webhook - In Shopify Admin, go to **Settings > Notifications > Webhooks** and check for failed deliveries ![Health Dashboard overview — system status, processing outcomes, and processing logs](/assets/docs/images/bundlesiq/health-dashboard-overview-top.png) 5. **Was there a processing error?** - Check the Health dashboard for a **Failed** status on the order - Look at the error message for details (e.g., missing component variant, API error) 6. **Has the order already been fulfilled?** - BundlesIQ only processes orders that have not been fulfilled. If the order's fulfillment status is not "unfulfilled," processing is skipped 7. **Was the order already processed?** - BundlesIQ is idempotent — it checks for existing transformation metadata before processing. If the order was already transformed, it will not process again. Check the order metafield `bundles_iq.transformation_audit` 8. **Are you in Parent-Only mode without realizing it?** - If your store default or bundle-level override is set to Parent-Only, the order was processed but no component lines were added — this is by design. See [Section 1.5](#15-why-were-no-component-lines-added-to-my-order) **If none of the above apply**, contact support with the order number and your BundlesIQ Health dashboard screenshot. You can submit a support ticket directly from the order's processing detail page: ![Submitting a support ticket from the order processing detail page](/assets/docs/images/bundlesiq/submitting-support-ticket.png) Support tickets include a live chat conversation with the Zapstra team: ![Live chat support conversation within BundlesIQ](/assets/docs/images/bundlesiq/support-ticket-live-chat.png) --- ### 2.2 Complete Error Code Reference When processing fails, BundlesIQ logs an error code on the Health dashboard. Below is the complete reference of all error codes, grouped by category. #### Authentication Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `AUTH_MISSING_CREDENTIALS` | No API credentials found for the store | Reinstall BundlesIQ or contact support to verify the installation | | `AUTH_MISSING_TOKEN` | Access token is missing or expired | Reinstall BundlesIQ from the Shopify App Store to generate a new token | | `AUTH_INVALID_TOKEN` | Access token is invalid or corrupted | Reinstall BundlesIQ from the Shopify App Store | | `AUTH_PERMISSIONS_REVOKED` | Required API permissions were revoked | Go to Shopify Admin > Settings > Apps and re-grant BundlesIQ's permissions, or reinstall the app | #### Shopify API Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `SHOPIFY_THROTTLED` | Shopify API rate limit hit | No action needed — BundlesIQ automatically waits and retries. If persistent during high-volume periods, processing may queue briefly | | `SHOPIFY_API_ERROR` | General Shopify API error | Check the error details on the Health dashboard. This is often a temporary Shopify-side issue. Retry from the Health dashboard if it persists | | `SHOPIFY_TIMEOUT` | Shopify API request timed out | Usually a temporary Shopify performance issue. BundlesIQ retries automatically. If persistent, check [Shopify Status](https://www.shopifystatus.com/) | #### Draft Order Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `DRAFT_OVERWRITTEN` | The draft order was modified by another process after BundlesIQ began its transformation | Retry or reprocess the draft order. If a third-party app is also editing drafts, coordinate processing order | | `DRAFT_CONCURRENT_EDIT` | Another process modified the draft order at the same time as BundlesIQ | See [Section 3.2](#32-concurrent-edit-detected-on-draft-orders) for details. Retry from the Health dashboard | #### Pricing Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `PRICE_VARIANCE_CRITICAL` | The calculated total differs significantly from the expected order total | See [Section 3.1](#31-price-variance-critical) for detailed diagnosis. Review the bundle's pricing configuration and check if component prices have changed in Shopify | | `PRICE_VALIDATION_FAILED` | Price calculations did not pass validation checks | Review the bundle's pricing strategy and component retail prices. Check for misconfigured discounts or pricing rules | #### Product and Variant Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `PRODUCT_NOT_FOUND` | A component product was deleted from Shopify | Re-add the product in Shopify, or update the bundle in BundlesIQ to use a different component product | | `VARIANT_NOT_FOUND` | A component variant was deleted or archived in Shopify | Update the bundle in BundlesIQ to use a valid variant. Check Shopify Admin for the variant's status | | `VARIANT_UNAVAILABLE` | A component variant exists but is not available for purchase | Check the variant's status in Shopify — it may be archived, out of stock, or unpublished | #### Validation Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `VALIDATION_COMPONENT_MISSING` | A required component is not configured in the bundle definition | Open the bundle in BundlesIQ and verify all components are present and correctly mapped | | `VALIDATION_CURRENCY_MISMATCH` | The order currency does not match the bundle's configured currency | Verify multi-currency settings. BundlesIQ requires the order currency to match the bundle's pricing currency | #### Entitlement and Processing Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `ENTITLEMENT_LIMIT_EXCEEDED` | Your plan's bundle processing limit has been reached | Upgrade your plan or wait for the next billing cycle | | `PROCESSING_BLOCKED_MAINTENANCE` | BundlesIQ is in maintenance mode and not processing orders | No action needed — processing resumes automatically when maintenance ends. Orders are queued and will be processed | | `RETRY_EXHAUSTED` | The maximum number of retry attempts has been reached | Review the original error that caused the retries. Fix the underlying issue, then use [Reprocess](#63-reprocessing-and-reverting-orders) from the Health dashboard | #### System Errors | Error Code | Meaning | Solution | |-----------|---------|----------| | `SYSTEM_ERROR` | An unexpected internal error occurred | Contact support with the order number and Health dashboard screenshot. These are rare and usually require investigation | | `CONFIGURATION_ERROR` | The bundle or store configuration is invalid | Review the bundle's configuration in BundlesIQ. Check for missing required fields, invalid pricing rules, or conflicting settings | #### BOM (Parent-Only) Errors These errors apply only to bundles using **Parent-Only (BOM) mode**: | Error Code | Meaning | Solution | |-----------|---------|----------| | `BOM_INSUFFICIENT_AVAILABLE` | A component does not have enough `available` inventory at the target location to fulfill the reservation | See [Section 3.3](#33-bom-specific-errors). Check component inventory levels at the fulfillment location | | `BOM_RESERVATION_FAILED` | The inventory reservation API call failed | See [Section 3.3](#33-bom-specific-errors). Retry from the Health dashboard. If persistent, check Shopify's inventory API status | | `BOM_CONSUMPTION_FAILED` | The inventory consumption (on fulfillment) failed | See [Section 3.3](#33-bom-specific-errors). Verify the reservation exists and has not already been consumed or released | | `BOM_RELEASE_FAILED` | The inventory release (on cancellation) failed | See [Section 3.3](#33-bom-specific-errors). Verify the reservation exists. May require manual inventory adjustment | | `BOM_LOCATION_NOT_FOUND` | The target inventory location could not be determined | Check the bundle's location strategy setting. Verify the fulfillment order has an assigned location, or that your configured single location exists and has inventory | --- ### 2.3 Understanding Attention Items Attention items appear on the Health dashboard to flag orders that need review. They differ from errors — the order may still have processed successfully, but something unusual was detected. | Attention Type | Severity | Meaning | Action | |---------------|----------|---------|--------| | `processing_failed` | Error | The order could not be processed | Check the error code in [Section 2.2](#22-complete-error-code-reference) and resolve the underlying issue. Retry or reprocess | | `price_variance_critical` | Error | The calculated price differs significantly from the expected total | See [Section 3.1](#31-price-variance-critical). Review pricing configuration and component prices | | `concurrent_edit_detected` | Warning | Another process modified the order during BundlesIQ's transformation | See [Section 3.2](#32-concurrent-edit-detected-on-draft-orders). Usually resolved by retrying | | `reservation_failed` | Error | Parent-Only mode: component inventory could not be reserved | Check component inventory levels and the location strategy. See [Section 3.3](#33-bom-specific-errors) | | `consumption_failed` | Warning | Parent-Only mode: reserved inventory could not be consumed on fulfillment | Verify the reservation still exists. May need manual inventory adjustment. See [Section 3.3](#33-bom-specific-errors) | | `release_failed` | Warning | Parent-Only mode: reserved inventory could not be released on cancellation | Verify the reservation exists. May need manual inventory adjustment. See [Section 3.3](#33-bom-specific-errors) | | `shopify_api_error` | Warning | A Shopify API error occurred during processing | Check error details. Usually transient — retry from the Health dashboard | --- ### 2.4 Understanding Transform Flags Transform flags are informational markers added to processed orders to explain pricing decisions. They appear on the Health dashboard under the order's processing details. | Flag Code | Title | Description | Severity | |----------|-------|-------------|----------| | `BUNDLE_EXCEEDS_COMPONENTS` | Bundle Price Exceeds Component Sum | The bundle retail price is higher than the total of its component prices. This may indicate a pricing configuration issue — the excess amount will be absorbed by the variance absorber | Medium | | `PRICE_INCREASE_NOT_POSSIBLE` | Price Increase Not Possible | A component price cannot be increased on a finalized Shopify order. This is a Shopify Order Edit API limitation — the component will be set to its original Shopify price instead of the higher allocated price | High | | `SPECIFIC_RETAIL_EXCEEDS_CONTEXTUAL` | Component Price Exceeds Shopify Price | A component's configured retail price in BundlesIQ is higher than its current Shopify price. The price cannot be increased on finalized orders, so the Shopify price is used instead | High | | `DOLLAR_DISCOUNT_EXCEEDS_RETAIL` | Discount Exceeds Retail Price | The configured dollar discount for a component exceeds its retail price, which would result in a negative line total. The discount is capped at the retail price | Medium | | `ORDER_LEVEL_PROMO_ROUNDING_VARIANCE` | Promo Rounding Variance | Distributing an order-level promotion across components created a small rounding difference. A reconciliation line was added to balance the total | Low | | `processing_blocked` | Processing Blocked | Order processing was blocked by entitlements, maintenance mode, or another gate condition. The order was not transformed | High | > **Flags do not necessarily mean something is wrong.** Many flags are informational — for example, `ORDER_LEVEL_PROMO_ROUNDING_VARIANCE` simply means BundlesIQ added a reconciliation line to handle a 1-2 cent rounding difference, which is normal. --- ## 3. Specific Error Deep Dives ### 3.1 Price Variance Critical **Error code:** `PRICE_VARIANCE_CRITICAL` **Symptom:** The order fails processing with a "price variance critical" error, or the Health dashboard shows a `price_variance_critical` attention item. **What it means:** BundlesIQ detected that the sum of the allocated component prices differs significantly from the original bundle price. This safety check prevents orders from being transformed with incorrect totals. **Common causes:** 1. **Component price changed in Shopify after bundle was configured** - If a component's Shopify price increased since you set up the bundle, BundlesIQ cannot increase the line item price on finalized orders (Shopify Order Edit API limitation) - The gap between the expected allocation and the actual achievable price creates a variance 2. **Discount code interaction** - A customer-applied discount code may create an allocation that conflicts with the bundle pricing strategy - Percentage discounts on bundles with dollar-off component pricing can create edge cases 3. **Currency rounding on international orders** - Multi-currency orders may produce rounding differences that exceed the variance threshold **Resolution:** 1. Open the order in the **Health dashboard** and review the pricing details 2. Check each component's current Shopify price vs. the bundle's configured allocation 3. If a component price changed, update the bundle's pricing configuration to reflect current prices 4. **Reprocess** the order from the Health dashboard after fixing the configuration 5. If the variance is small and expected, contact support to discuss adjusting the variance threshold --- ### 3.2 Concurrent Edit Detected on Draft Orders **Error code:** `DRAFT_CONCURRENT_EDIT` **Symptom:** A draft order fails processing with a "concurrent edit" error. **What it means:** While BundlesIQ was transforming the draft order, another process (another app, a Shopify Admin user, or a Shopify Flow) modified the same draft order. Shopify's Draft Order API uses optimistic concurrency — if the draft is modified between BundlesIQ reading it and writing the transformation, the write fails. **Common causes:** 1. **Another app editing draft orders** — Apps that modify draft orders (e.g., discount apps, tax apps) may conflict 2. **Manual editing during processing** — A staff member edited the draft order in Shopify Admin while BundlesIQ was processing it 3. **Shopify Flow automation** — A Flow that modifies draft orders may trigger at the same time as BundlesIQ **Resolution:** 1. **Retry** — Click **Retry** on the Health dashboard. In most cases, the concurrent edit was a one-time race condition and the retry succeeds 2. **If retries keep failing** — Identify the other process that is editing the draft order and coordinate timing. You may need to: - Disable other draft order apps temporarily - Adjust Shopify Flow timing - Ensure staff do not manually edit draft orders before BundlesIQ processes them > **This error does not apply to regular orders.** Regular order processing uses the Order Edit API, which has different concurrency semantics. --- ### 3.3 BOM-Specific Errors These errors apply only to bundles using **Parent-Only (BOM) mode**. They relate to inventory reservation, consumption, and release operations. #### BOM_INSUFFICIENT_AVAILABLE **Symptom:** Order processing fails because a component does not have enough available inventory. **Cause:** The component's `available` quantity at the target inventory location is less than what the bundle requires. **Resolution:** 1. Check the component's inventory in Shopify Admin at the relevant location 2. Restock the component or adjust the location strategy 3. If using "Fulfillment order location" strategy, verify the fulfillment order is assigned to a location with sufficient stock 4. Reprocess the order after inventory is available #### BOM_RESERVATION_FAILED **Symptom:** The inventory reservation API call failed even though sufficient inventory appears to be available. **Cause:** A transient Shopify Inventory API error, or another process modified the inventory between the availability check and the reservation call. **Resolution:** 1. Retry from the Health dashboard — this usually resolves transient API issues 2. If persistent, check if another inventory management app is conflicting 3. Verify the inventory location is correctly configured in Shopify #### BOM_CONSUMPTION_FAILED **Symptom:** When the order was fulfilled, BundlesIQ could not consume (decrement) the reserved inventory. **Cause:** The reservation may have already been manually released or consumed by another process, or a Shopify API error occurred. **Resolution:** 1. Check the component's inventory levels — if the reservation was already consumed, no action is needed 2. If the inventory is incorrect, manually adjust it in Shopify Admin 3. Check the Health dashboard logs for the specific API error #### BOM_RELEASE_FAILED **Symptom:** When the order was cancelled, BundlesIQ could not release the reserved inventory back to available. **Cause:** The reservation may have already been consumed (if the order was fulfilled before cancellation) or released by another process. **Resolution:** 1. Check if the inventory was already released — if available quantities look correct, no action is needed 2. If inventory is stuck in reserved state, manually adjust it in Shopify Admin 3. Contact support if this occurs repeatedly #### BOM_LOCATION_NOT_FOUND **Symptom:** BundlesIQ cannot determine which inventory location to use for the reservation. **Cause:** Depends on the location strategy: - **"Fulfillment order location"** — The order does not have a fulfillment order with an assigned location, or the assigned location does not carry the component - **"Single location"** — The configured location does not exist or does not have the component stocked **Resolution:** 1. Verify the location strategy in **BundlesIQ > Settings** or the bundle's override settings 2. If using fulfillment order location, check that the order has a fulfillment order assigned to a valid location 3. If using single location, verify the configured location exists and has the component products stocked 4. Ensure components are stocked at the relevant location in Shopify Admin --- ### 3.4 Shopify API Errors **Error codes:** `SHOPIFY_THROTTLED`, `SHOPIFY_API_ERROR`, `SHOPIFY_TIMEOUT` **Symptom:** Processing fails with a Shopify API-related error. **How BundlesIQ handles Shopify API issues:** - **Rate limits (`SHOPIFY_THROTTLED`):** BundlesIQ automatically backs off and retries with exponential delay. No action is needed in most cases. During high-volume events (flash sales, bulk imports), you may see a brief delay in processing. - **API errors (`SHOPIFY_API_ERROR`):** These are usually transient. BundlesIQ retries automatically up to the configured maximum attempts (default: 1 automatic retry). - **Timeouts (`SHOPIFY_TIMEOUT`):** The Shopify API took too long to respond. BundlesIQ retries automatically. **When to take action:** - If a Shopify API error persists after automatic retries, check [Shopify Status](https://www.shopifystatus.com/) for ongoing platform issues - If rate limiting is frequent, review whether other apps on your store are consuming excessive API quota - Click **Retry** on the Health dashboard to manually trigger a retry after the issue resolves --- ### 3.5 Auth Errors **Error codes:** `AUTH_MISSING_CREDENTIALS`, `AUTH_MISSING_TOKEN`, `AUTH_INVALID_TOKEN`, `AUTH_PERMISSIONS_REVOKED` **Symptom:** Processing fails with an authentication error. All orders fail, not just specific bundles. **Common causes:** 1. **App permissions were revoked** — Someone changed the app's permissions in Shopify Admin 2. **App was uninstalled and reinstalled** — The previous access token was invalidated 3. **Shopify token rotation** — Rare, but Shopify may rotate tokens during platform updates **Resolution:** 1. Go to **Shopify Admin > Settings > Apps and sales channels** 2. Find **BundlesIQ** and click **Manage** 3. If permissions are missing, click to re-grant them 4. If the issue persists, **uninstall and reinstall** BundlesIQ from the Shopify App Store 5. After reinstallation, verify your bundles and settings are intact (they are stored server-side and will reconnect) > **All queued orders will process** once authentication is restored. No orders are lost. --- ## 4. Pricing and Reporting Troubleshooting ### 4.1 Discount or Price Looks Wrong **Symptoms:** After bundle processing, the component prices on the order do not match what you expected. **Check these in order:** 1. **Verify your pricing strategy** - Open the bundle in BundlesIQ and check the pricing mode (bundle-led or component-led) and strategy - Review the price preview to see the expected allocation 2. **Check for pricing warnings (transform flags)** - In the BundlesIQ Health dashboard, look for flags on the order: ![Price Variance warning with explanation, suggested actions, and prevention tips](/assets/docs/images/bundlesiq/bundles-issue-warning.png) - `BUNDLE_EXCEEDS_COMPONENTS` — Bundle price is higher than the sum of component retails. See [Section 2.4](#24-understanding-transform-flags) - `PRICE_INCREASE_NOT_POSSIBLE` — A component could not be set to the target price because the Order Edit API does not allow price increases. See [Section 2.4](#24-understanding-transform-flags) - `SPECIFIC_RETAIL_EXCEEDS_CONTEXTUAL` — A component's configured retail price in BundlesIQ is higher than its current Shopify price. The Shopify price is used instead - `DOLLAR_DISCOUNT_EXCEEDS_RETAIL` — A dollar-off discount is larger than the component's retail price. The discount is capped at the retail price - `ORDER_LEVEL_PROMO_ROUNDING_VARIANCE` — A small rounding difference was detected when distributing an order-level promotion. A reconciliation line was added to balance the total 3. **Check if a Shopify discount code was applied** - If the customer used a discount code at checkout, BundlesIQ factors it into the price allocation - The combined effect of bundle allocation + discount code may produce unexpected-looking per-component prices 4. **Check for rounding variance** - Small differences of 1-10 cents can occur due to rounding during price allocation - BundlesIQ's variance absorber automatically corrects these, but you may see slightly different discount percentages on individual components 5. **Check the component's current Shopify price** - BundlesIQ uses the component's current Shopify price (contextual price) when calculating discounts - If a component's price changed after the bundle was configured, the allocation may differ from the preview --- ### 4.2 Reporting Does Not Match What I Expect **Symptoms:** Shopify Analytics or your reporting tools show unexpected revenue attribution, best-seller rankings, or sales data after implementing BundlesIQ. **Understand the root cause:** Revenue attribution depends entirely on your handling mode: | Handling Mode | Revenue Attributed To | |--------------|----------------------| | Hybrid | Component SKUs (components carry the price) | | Operational | Component SKUs (components carry the price) | | Reporting | Bundle (ghost) SKU (bundle carries the price) | | Parent-Only (BOM) | Bundle (ghost) SKU (bundle is the only item on the order) | **If you want revenue on the bundle SKU:** Use **Reporting mode** or **Parent-Only (BOM) mode** **If you want revenue on component SKUs:** Use **Hybrid** or **Operational mode** **If you already processed orders in the wrong mode:** - Change your handling mode going forward (new orders only) - Previously processed orders are not retroactively changed - You may need to manually reconcile historical data in your reporting tools **Best-seller rankings:** - In Hybrid and Operational modes, individual components may appear as top sellers instead of the bundle - In Reporting and Parent-Only modes, the bundle product appears in best-seller rankings **Channel feeds (Meta, TikTok, Google):** - Some channel integrations read order data to determine product performance - In Hybrid and Operational modes, channel analytics may attribute sales to component SKUs - If channel attribution is important, consider Reporting mode --- ## 5. Inventory and Availability ### 5.1 Bundle Shows Out of Stock **Symptoms:** Your bundle product shows as "Out of stock" on the storefront, but you believe the components have inventory. **Check these in order:** 1. **Check all component inventory levels** - Bundle availability is determined by the **least available component** - Open each component product in Shopify Admin and check its inventory at the relevant location - Even one component at zero makes the entire bundle unavailable 2. **Check the correct location** - If you have multiple Shopify locations, verify inventory at the location that serves online orders - A component might have stock at one location but not another 3. **Check the ghost SKU's inventory tracking setting** - If inventory tracking is enabled on the ghost SKU, BundlesIQ sets its available quantity based on components - If inventory tracking is disabled, the product should always show as in stock — check for other reasons it might be hidden (product status, channel availability) 4. **Check "Continue selling when out of stock"** - On the ghost SKU variant: if this is disabled and inventory is 0, Shopify shows "Out of stock" - If you want to allow purchases even when calculated availability is 0, enable this setting (but be aware of overselling risk) 5. **Check if inventory sync is enabled** - In **BundlesIQ > Settings**, verify **Sync bundle inventory** is enabled - On the specific bundle, verify inventory sync is not disabled at the bundle level 6. **Calculate availability manually** - For each component: divide available quantity by quantity per bundle - The minimum result is the bundle availability - Compare with the ghost SKU's current inventory in Shopify 7. **Parent-Only (BOM) mode: check reserved quantities** - If using Parent-Only mode, reserved component inventory reduces the available quantity - If many orders have reserved but not yet consumed components, the available quantity may be lower than expected - Check the component's `reserved` vs. `available` breakdown in Shopify Admin --- ### 5.2 Parent-Only: Component Inventory Not Reserved **Symptoms:** You placed an order with a Parent-Only bundle, but the component inventory `reserved` quantities did not change. **Check these in order:** 1. **Was the order processed?** - Check the BundlesIQ Health dashboard for the order status - If the order is not listed, the webhook may not have been received 2. **Check the reserve timing setting** - If reserve timing is set to `orders/paid`, inventory is only reserved after payment is confirmed - If the order is unpaid, switch to `orders/create` to reserve immediately, or wait for payment 3. **Check the location strategy** - If set to "Fulfillment order location," verify the order has a fulfillment order assigned to a location with component inventory - If set to "Single location," verify the configured location has sufficient component stock 4. **Check component inventory levels** - If a component has zero `available` stock at the target location, the reservation may fail - Check the Health dashboard for error details — see [Section 3.3](#33-bom-specific-errors) for BOM-specific error resolution --- ## 6. Procedures and Operational Guidance ### 6.1 Retry vs. Reprocess: Which One Should I Use? Both options are available on the Health dashboard, but they do different things: | | Retry | Reprocess | |-|-------|-----------| | **What it does** | Republishes the existing write request directly to the writer service | Deletes stale instances, strips all `BIQ_*` tags, and re-runs the full pipeline from detection through transformation | | **When to use** | Transient errors: rate limits, API timeouts, temporary Shopify issues | Configuration changes: updated bundle, changed handling mode, stale data | | **Speed** | Fast — skips detection and transformation, goes straight to Shopify mutation | Slower — full pipeline re-run including webhook-worker detection | | **Attempt limit** | Capped at configured `max_attempts` (default: 5 total including automatic retries) | Creates a fresh processing instance — attempt counter resets | | **Safe for** | Any failed order | Failed or successfully processed orders (force reprocess for already-processed orders) | **Decision guide:** - The order failed with `SHOPIFY_THROTTLED`, `SHOPIFY_API_ERROR`, or `SHOPIFY_TIMEOUT` → **Retry** - The order failed with `DRAFT_CONCURRENT_EDIT` → **Retry** (the concurrent edit was likely a one-time race condition) - You changed the bundle's configuration (components, pricing, handling mode) → **Reprocess** - The order has stale or corrupted transformation data → **Reprocess** (force mode) - The order failed with `PRODUCT_NOT_FOUND` or `VARIANT_NOT_FOUND` and you fixed the product → **Reprocess** - You are not sure → Start with **Retry**. If it fails again with the same error, investigate and then **Reprocess** after fixing the issue > **Parent-Only (BOM) mode note:** Reprocessing a Parent-Only order will release any existing inventory reservations before re-running the pipeline. If the order has already been partially fulfilled, use caution. --- ### 6.2 How to Tell If an Order Was Processed There are several ways to confirm whether BundlesIQ has processed an order: 1. **Check the order tags in Shopify Admin** - `BIQ_READY` — The order was successfully processed - `BIQ_PROCESSING` — Processing is currently in progress - `BIQ_ERROR` — Processing failed (check the Health dashboard for details) - `BIQ_REVERTED` — A draft order was reverted to its pre-transformation state 2. **Check the order metafield** - Look for the `bundles_iq.transformation_audit` metafield on the order - This contains the full transformation record including bundle mappings, pricing allocations, and flags 3. **Check the BundlesIQ Health dashboard** - Search for the order by number or ID - The dashboard shows the processing status, timeline, and any errors or attention items 4. **Check for component line items** (Hybrid, Operational, and Reporting modes only) - In Hybrid mode: bundle at $0, components with prices - In Operational mode: bundle removed, only components remain - In Reporting mode: bundle at original price, components at $0 - In Parent-Only mode: no visible changes on the order — use the Health dashboard or `BIQ_READY` tag instead --- ### 6.3 Reprocessing and Reverting Orders BundlesIQ provides admin tools to reprocess failed orders and revert draft order transformations. These tools are accessible from the Shopify Admin order/draft order detail page via the **Bundle Tools** action menu. #### Reprocessing (Orders and Draft Orders) Reprocessing re-runs the full bundle transformation pipeline for an order. Use this when: - Processing failed and the error has been resolved (e.g., a missing variant was re-added) - The bundle configuration was changed and you want to re-transform an order - Stale processing state needs to be cleared See [Section 6.1](#61-retry-vs-reprocess-which-one-should-i-use) for guidance on when to retry vs. reprocess. **How to reprocess:** ![Accessing Reprocess Order Bundle from the More actions menu in Shopify Admin](/assets/docs/images/bundlesiq/selecting-order-app-extension.png) 1. **Open** the order or draft order in Shopify Admin 2. **Click** the **Bundle Tools** action (in the "More actions" menu) 3. **Click** **Reprocess Bundle** 4. If the order was already successfully processed, BundlesIQ will warn you and offer a **Force Reprocess** option ![Reprocess Bundle dialog — only failed or pending bundles will be reprocessed](/assets/docs/images/bundlesiq/order-app-extension.png) **What happens during reprocessing:** 1. Existing bundle instances in BundlesIQ are cancelled and deleted 2. All `BIQ_*` tags are stripped from the order (including `BIQ_PROCESSING`, `BIQ_READY`, `BIQ_ERROR`, and `BIQ_REVERTED`) 3. If the bundle metafield already exists on the order, it is deleted (force mode only) 4. The full order data is fetched from Shopify and published for processing 5. The webhook-worker detects bundles and processes them as if the order were new > **Force Reprocess** is a safety escalation. It deletes existing processed instances and metafields before re-running the pipeline. Use it only when you are certain the previous transformation needs to be replaced. > **Parent-Only (BOM) mode:** Reprocessing releases any existing inventory reservations before re-running the pipeline. If the order has already been partially fulfilled, some reservations may have already been consumed — use caution and verify inventory levels after reprocessing. #### Reverting (Draft Orders Only) Reverting undoes a bundle transformation on a draft order, restoring it to its pre-BundlesIQ state. This is only available for draft orders — regular orders cannot be reverted because the Order Edit API does not support removing previously added line items. **How to revert:** 1. **Open** the draft order in Shopify Admin 2. **Click** the **Bundle Tools** action 3. **Choose** one of: - **Revert Only** — Removes all bundle components and restores the original ghost SKU lines. The draft order is left in its pre-transformation state and will not be re-processed (a `BIQ_REVERTED` tag is applied to prevent automatic re-transformation) - **Revert & Reprocess** — Reverts the draft order and then immediately re-runs the full processing pipeline. All `BIQ_*` tags are stripped and fresh processing begins **What reverting does by handling mode:** | Line type | Action | |-----------|--------| | Component lines (added by BundlesIQ) | **Removed** | | Adjustment lines (e.g., Bundle Allocation) | **Removed** | | Hybrid bundle lines (with "Bundle transformation" discount) | **Kept**, discount removed (restored to original price) | | Operational bundle lines (quantity was set to 0) | **Restored** — ghost SKU variant is re-added with original quantity | | Reporting bundle lines | **Kept** as-is (they were never modified) | | Non-bundle lines | **Kept** as-is | #### The BIQ_REVERTED Tag When a draft order is reverted (without reprocessing), BundlesIQ applies the `BIQ_REVERTED` tag. This tag tells the webhook-worker to skip the draft order when the `draft_orders/update` webhook fires (which Shopify sends in response to the revert mutation). Without this tag, the worker would immediately re-transform the draft order. - **Revert Only**: `BIQ_REVERTED` tag stays — prevents automatic re-transformation - **Revert & Reprocess**: All `BIQ_*` tags are stripped — the intentional re-publish triggers clean reprocessing --- ## 7. Frequently Asked Questions ### 7.1 How Long Does Processing Take? BundlesIQ processes orders asynchronously after receiving the webhook from Shopify: | Scenario | Expected Time | |----------|--------------| | Single bundle, few components | 2-5 seconds | | Multiple bundles on one order | 5-15 seconds | | High-volume periods | Up to 30 seconds | | Failed + automatic retry | Cooldown period (default: 5 minutes) + processing time | If 3PL protection is enabled, the order is held until processing completes, so timing variations do not cause fulfillment issues. --- ### 7.2 Do Line Item Properties Transfer to Components? BundlesIQ does not currently transfer line item properties (such as gift messages, engraving text, or custom fields) from the ghost SKU line item to component line items. **Workaround:** If you need line item properties on components, you can: - Add the properties manually after BundlesIQ processes the order - Use a Shopify Flow to copy properties from the original line to component lines - Contact support to discuss your specific use case --- ### 7.3 Can Customers Still Apply Discount Codes? Yes. Customers can apply Shopify discount codes at checkout as normal. BundlesIQ detects any applied discounts and factors them into the component price allocation during transformation. **How it works:** - The discount code is applied to the ghost SKU at checkout - BundlesIQ detects the discount and its type (percentage, fixed amount, BOGO, etc.) - During transformation, BundlesIQ distributes both the bundle allocation discount and the checkout discount across components **Limitations:** - Shopify automatic discounts work the same way — BundlesIQ factors them in - Discount stacking behavior is governed by Shopify's rules (e.g., only one discount code per order unless your store supports stacking) --- ### 7.4 Does BundlesIQ Work with Shopify POS? Yes. BundlesIQ processes orders from all Shopify channels, including POS. When a POS order contains a bundle ghost SKU, it is processed the same way as an online order. **Note:** BundlesIQ does not provide a POS-specific UI. Staff using POS should add the ghost SKU product to the sale; BundlesIQ transforms the order after it is created. --- ### 7.5 What Happens If I Change My Handling Mode After Processing Orders? The mode change applies to **new orders only**. Previously processed orders are not retroactively modified. See [Section 1.7](#17-i-changed-my-handling-mode-but-old-orders-did-not-change) for details. **Per-bundle overrides:** You can set different handling modes per bundle. This means you can run Operational mode for your wholesale bundles and Reporting mode for your DTC bundles simultaneously. --- ### 7.6 Why Does the Customer See Something Different on Their Order Confirmation Email? The order confirmation email is sent by Shopify **immediately** after order creation — before BundlesIQ receives the webhook and processes the order. This means the email shows the original, pre-transformation order (just the bundle product at the purchase price). After processing (typically 2-15 seconds later), the order in Shopify Admin shows the transformed version. If the customer checks their order status page or account history after processing completes, they see the transformed order. See [Section 1.6](#16-what-does-the-customer-see-after-checkout) for the full breakdown. > **Tip:** If you want the customer-facing order to match the email as closely as possible, use **Reporting mode** or **Parent-Only mode** — these preserve the bundle name and price on the order, so the transformed order looks very similar to the email. --- ### 7.7 Multi-Bundle Orders: What to Expect When a single order contains multiple bundles, BundlesIQ processes all bundles in a single transformation: - **All bundles on the order are detected** during the initial webhook processing - **Each bundle is transformed independently** according to its own handling mode (if per-bundle overrides are set) - **Component lines are added for each bundle** — if two bundles share a component variant, those component lines appear separately (one per bundle) - **Processing time increases** slightly with multiple bundles (5-15 seconds typical) **Mixed handling modes on one order:** If one bundle is set to Hybrid mode and another to Operational mode, each bundle's transformation follows its own mode rules. The order may show a mix of $0 bundle lines, removed bundle lines, and priced component lines. > **Tip:** For simplicity, we recommend using the same handling mode for all bundles on a single store. Mixed modes on one order are supported but can create confusing-looking orders. --- ### 7.8 Processing Takes Longer Than Expected **Symptoms:** Orders are not transformed within the expected 2-15 second window. **Possible causes:** 1. **High webhook volume** — During sales events or bulk order imports, webhook processing may queue 2. **Shopify API throttling** — If your store is hitting Shopify's API rate limits, BundlesIQ waits and retries 3. **Complex bundles** — Bundles with many components or multiple bundles on a single order take longer 4. **Retry in progress** — If the initial processing failed, BundlesIQ may be waiting for the cooldown period before retrying **What to do:** ![Processing timeline showing each step from webhook received through completion](/assets/docs/images/bundlesiq/health-dashboard-processing-timeline.png) - Check the Health dashboard for the order's status - If the order shows "Pending" or "Processing," wait a few minutes - If the order shows "Failed," check the error message and resolve the issue - If 3PL protection is enabled, the order remains held until processing completes — no fulfillment risk --- ### 7.9 Launch Week Common Questions If you just went live with BundlesIQ, here are the most common situations during the first week: #### "My 3PL imported orders before BundlesIQ processed them" If your 3PL pulls orders immediately after creation (before BundlesIQ's 2-15 second processing window), the 3PL may have imported the pre-transformation order. **Solution:** Enable **3PL protection** (fulfillment hold) in **BundlesIQ > Settings**. This places a fulfillment hold on orders until processing completes, preventing premature 3PL import. The hold is released automatically after successful transformation. #### "My warehouse is confused by $0 component lines" If using Reporting mode, component lines appear at $0. Some warehouse staff or 3PLs interpret this as "free items" or are confused by the zero-dollar lines. **Solutions:** - Switch to **Operational mode** if the warehouse only needs real SKUs and prices (no bundle reference needed) - Switch to **Hybrid mode** if you want the bundle reference visible but components priced - Train warehouse staff that $0 lines in Reporting mode are fulfillment-only items — the bundle line carries the total price - Use the bundle header feature in Writer Options to add grouping labels #### "Some orders were processed but others were not" Check these common launch-week causes: 1. **Processing scope:** Is it set to "All orders" or "Tagged only"? If tagged only, verify the tags 2. **Bundle status:** Are all bundles set to **Active**? Draft bundles are not processed 3. **Order timing:** Orders placed before BundlesIQ was installed/enabled are not retroactively processed 4. **Ghost SKU mismatch:** Verify the ghost SKU variant ID in the bundle matches the actual Shopify product variant #### "I launched with the wrong handling mode" No problem — change the mode in **BundlesIQ > Settings** (or per-bundle override). The new mode applies to all new orders immediately. Previously processed orders are not affected. If you need to re-transform specific draft orders, use [Revert & Reprocess](#63-reprocessing-and-reverting-orders). --- ## 8. Related Pages - [Getting Started](/documentation/bundlesiq/getting-started) - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [How Orders Look in Each Mode](/documentation/bundlesiq/order-representation) - [Pricing Strategy Setup](/documentation/bundlesiq/pricing-strategy) - [Inventory Rules](/documentation/bundlesiq/inventory-rules) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) - [Global Settings Overview](/documentation/bundlesiq/global-settings) --- ### Go-Live Checklist # Go-Live Checklist Use this checklist to verify that BundlesIQ is working correctly before processing real customer orders. Complete each step in order and confirm the expected results. ## What You Will Accomplish You will systematically verify that bundle creation, order transformation, inventory behavior, pricing, and 3PL protection are all working as expected in your store. ## When to Use This Guide - You are launching BundlesIQ for the first time - You have made significant configuration changes (handling mode, pricing strategy, new bundles) - You want to verify behavior after a BundlesIQ update ## Pre-Launch Checklist ### 1. Verify Bundle Configuration - [ ] **All bundles are Active** — Open **BundlesIQ > Bundles** and confirm each bundle you want to process has an **Active** status - [ ] **Ghost SKU products are correctly configured** — For each bundle, verify the ghost SKU product in Shopify: - Has a clear, unique SKU - Has inventory tracking set appropriately (tracked by BundlesIQ, or untracked) - Has "This is not a physical product" set for shipping (recommended) - [ ] **Components are valid** — Each component variant exists in Shopify, is not archived, and has inventory at the correct location(s) - [ ] **Pricing preview looks correct** — Open each bundle and review the price preview section. Verify totals match and no warnings are displayed - [ ] **Handling mode is set** — Confirm your default handling mode in **Settings**, and any bundle-level overrides - [ ] **(Parent-Only only) Reserve timing and location strategy are set** — If using Parent-Only mode, confirm the reserve timing (`orders/paid` or `orders/create`) and location strategy in **Settings > Parent-Only (BOM) Settings** ### 2. Place a Test Order (Standard) 1. **Create** a test order through your storefront (use the Bogus Gateway or a test payment method) 2. **Add** a bundle product to the cart and complete checkout 3. **Wait** 5-15 seconds for processing 4. **Verify in Shopify Admin:** | Check | Expected Result | |-------|----------------| | Component line items appear | Yes — matching your bundle's component list and quantities (except Parent-Only: no components on order) | | Bundle line item behavior matches handling mode | Hybrid: $0 / Reporting: original price / Operational: removed / Parent-Only: original price, no components | | Order total unchanged | Yes — matches the original bundle purchase price | | Discount labels are present on components | Yes (in Hybrid and Operational modes) | | BIQ_READY tag present | Yes (if 3PL protection is enabled) | 5. **Verify in BundlesIQ Health dashboard:** | Check | Expected Result | |-------|----------------| | Order appears in recent activity | Yes | | Processing status | **Processed** (green) | | No flags or warnings | Ideally yes; investigate any warnings | ### 3. Place a Test Draft Order (If Using B2B) 1. **Create** a draft order in Shopify Admin containing a bundle product 2. **Wait** 5-15 seconds for processing 3. **Verify** the draft order shows the correct component line items 4. **Complete** the draft order (mark as paid or send invoice) 5. **Verify** the resulting order is also correctly transformed ### 4. Verify Inventory Decrements After the test order is placed: 1. **Check** each component product's inventory in Shopify Admin 2. **Confirm** quantities were decremented by the order amounts 3. **Check** the ghost SKU's inventory (if sync is enabled): | Check | Expected Result | |-------|----------------| | Component A inventory decreased | By `quantity_per_bundle × order_quantity` | | Component B inventory decreased | By `quantity_per_bundle × order_quantity` | | Ghost SKU inventory recalculated | Reflects new availability based on remaining component stock | ### 5. Test Refund Behavior 1. **Open** the test order in Shopify Admin 2. **Click** **Refund** and select the appropriate line items for your handling mode: - Hybrid / Operational: select component line items - Reporting: select the bundle line item 3. **Process** the refund with "Restock items" enabled 4. **Verify** component inventory is restocked 5. **Verify** bundle availability is recalculated (check ghost SKU inventory) ### 6. Test 3PL Protection (If Enabled) 1. **Place** a test order containing a bundle 2. **Immediately check** the order in Shopify Admin: | Check | Expected Result | |-------|----------------| | `BIQ_PROCESSING` tag present | Yes (immediately after order creation) | | Fulfillment status | "On hold" (if fulfillment holds are enabled) | | Order not yet importable by 3PL | Correct | 3. **Wait** for processing to complete 4. **Check again:** | Check | Expected Result | |-------|----------------| | `BIQ_PROCESSING` tag removed | Yes | | `BIQ_READY` tag present | Yes | | Fulfillment hold released | Yes | | Order now importable by 3PL | Yes | ### 7. Test Error Recovery and Reprocessing 1. **Temporarily deactivate** a component variant in Shopify (or set its status to draft) 2. **Place** an order containing the affected bundle 3. **Verify** in BundlesIQ Health dashboard: | Check | Expected Result | |-------|----------------| | Order shows as **Failed** | Yes | | Error message explains the issue | Yes (e.g., "Variant not found") | | `BIQ_ERROR` tag present on order | Yes (if 3PL protection is enabled) | | `BIQ_READY` tag NOT present | Correct | 4. **Re-activate** the component variant 5. **Open** the order in Shopify Admin, click **Bundle Tools** > **Reprocess Bundle** 6. **Verify** the order is successfully processed (component lines appear, `BIQ_READY` tag applied) **Test draft order revert (optional, if using draft orders):** 1. **Create** a draft order with a bundle product and wait for processing 2. **Open** the draft order, click **Bundle Tools** > **Revert Only** 3. **Verify** component lines are removed and the draft returns to its original state 4. **Click** **Bundle Tools** > **Revert & Reprocess** on another test draft 5. **Verify** the draft is reverted and then re-processed successfully ### 8. Test Parent-Only Inventory Lifecycle (If Using Parent-Only Mode) If your bundle uses Parent-Only (BOM) mode, verify the full inventory lifecycle: 1. **Note** the current `available` and `reserved` quantities for each component at the target location 2. **Place** a test order containing the bundle 3. **Wait** for processing and verify: | Check | Expected Result | |-------|----------------| | Component `reserved` quantity increased | By `quantity_per_bundle × order_quantity` | | Component `available` quantity decreased | By the same amount | | Bundle line on order unchanged | Yes — at original price, no component lines | | Health dashboard shows Processed | Yes | 4. **Fulfill** the order and verify: | Check | Expected Result | |-------|----------------| | Component `reserved` quantity decreased | Back to pre-order level (stock consumed) | | Component `available` quantity unchanged | Same as after reservation | 5. **(Optional) Cancel a separate test order** and verify: | Check | Expected Result | |-------|----------------| | Component `reserved` quantity decreased | Released back | | Component `available` quantity increased | Stock returned to available | ### 9. Test with a Discount Code (Optional) 1. **Create** a Shopify discount code (e.g., 10% off) 2. **Place** a test order using the bundle product and apply the discount code 3. **Verify** the discount is correctly distributed across component line items 4. **Verify** the order total matches the expected amount (bundle price minus discount) ### 10. Verify Multi-Bundle Orders (If Applicable) If customers can purchase multiple bundles or multiple different bundles in one order: 1. **Place** a test order with 2+ bundle products (or quantity > 1 of one bundle) 2. **Verify** all bundles are processed 3. **Verify** component quantities reflect the correct totals 4. **Verify** the order total is correct ## Go-Live Decision Complete all applicable checks above. If everything passes: 1. **Confirm** your handling mode, pricing strategy, and 3PL protection are set to production values 2. **Enable** processing for all order types you need (orders, draft orders) 3. **Set** your processing scope (all orders, or tagged only) 4. **Notify** your fulfillment team about the new order format and any tag-based workflows 5. **Monitor** the BundlesIQ Health dashboard closely for the first 24-48 hours ## Post-Launch Monitoring For the first few days after going live: - **Check** the Health dashboard daily for failed orders or unexpected flags - **Spot-check** 2-3 real orders to verify they look correct - **Confirm** with your warehouse or 3PL that they are receiving the correct component information - **Review** inventory levels to ensure sync is working as expected ## Common Mistakes - **Going live without testing refunds** — Refund behavior differs by handling mode. Test before you have a real customer return - **Not notifying the fulfillment team** — Your warehouse staff need to know that orders will now show component line items instead of (or in addition to) the bundle product - **Skipping the 3PL protection test** — If your 3PL imports orders automatically, this is the most critical test ## Related Pages - [Quickstart Guide](/documentation/bundlesiq/quickstart) - [Handling Modes Explained](/documentation/bundlesiq/handling-modes) - [3PL Integration Guide](/documentation/bundlesiq/tpl-integration) - [Troubleshooting](/documentation/bundlesiq/troubleshooting) --- ### Billing & Plans # Billing and Plans BundlesIQ offers tiered pricing based on your order volume. The Free plan lets you get started at no cost. ## Plans Overview | Plan | Monthly Price | Included Bundle Units | Included Monitored Orders | |------|--------------|----------------------|--------------------------| | **Free** | $0/mo | 25 | 1,000 | | **Core** | $9.99/mo | 250 | 5,000 | | **Ops** | $49/mo | 10,000 | 25,000 | | **Scale+** | $129/mo | 100,000 | 250,000 | ## Key Terms - **Bundle units** — The total number of bundle parent line items processed ("explosions") during the billing cycle. If a customer orders 3 of a bundle product, that counts as 3 bundle units - **Monitored orders** — The total number of orders and draft orders created in your store during the billing cycle. This includes all orders, not just those containing bundles ## Free Plan The Free plan is always free — there is no trial period. You can activate it immediately with no credit card required. - 25 bundle units per billing cycle - 1,000 monitored orders per billing cycle - Full access to all BundlesIQ features within those limits - When you reach either limit, processing stops for the remainder of the billing cycle. Upgrade to a paid plan to continue processing immediately. ## Free Trial All **paid plans** (Core, Ops, Scale+) include a **14-day free trial**. During the trial: - Full access to all features on your selected plan - Usage is tracked but no charges are applied - You can change plans during the trial - The trial starts when you approve the subscription The Free plan has no trial — it is always free. ## Scale+ Overages The Scale+ plan includes usage-based overages for shops that exceed the included limits: | Overage Type | Rate | |-------------|------| | **Bundle units** | $12 per 10,000 units over 100,000 | | **Monitored orders** | $15 per 100,000 orders over 250,000 | Overages are billed periodically during the billing cycle with a transparent monthly cap. You can view your current usage and projected overages in the app. ### Usage Cap Scale+ includes a configurable monthly spending cap for overages (default: $1,000). This cap prevents unexpected charges: - You can increase or decrease the cap from within the app - If usage approaches the cap (approximately 90%), BundlesIQ shows a notification - Increasing the cap requires merchant approval through Shopify's standard confirmation flow ## Choosing the Right Plan ### Plan Recommendation Guide 1. **Check your monthly order volume** — In Shopify Admin, look at your total orders created per month 2. **Estimate bundle units** — How many bundle products do you sell per month? Each unit purchased counts 3. **Match to a plan** — Choose the plan where your volumes fit within the included limits | Your Volume | Recommended Plan | |------------|-----------------| | Up to 25 bundle units, 1,000 orders/mo | **Free** | | Up to 250 bundle units, 5,000 orders/mo | **Core** | | Up to 10,000 bundle units, 25,000 orders/mo | **Ops** | | Higher volume or need overage flexibility | **Scale+** | ### Plan Selection in the App BundlesIQ runs a preflight check when you select a plan: - **Order volume check** — If your last 30 days of orders significantly exceed the plan's included limit, BundlesIQ will warn you or suggest a higher tier - **Billing currency** — Displayed in your store's app billing currency ## Changing Plans You can upgrade or downgrade your plan at any time: 1. **Navigate** to **BundlesIQ > Settings > Billing** (or **BundlesIQ > Billing**) 2. **Select** the new plan 3. **Approve** the plan change through Shopify's confirmation flow 4. The new plan takes effect immediately **When upgrading:** You get immediate access to the higher plan's limits. **When downgrading:** The lower plan takes effect at the start of your next billing cycle. ## What Happens When You Exceed Limits ### Free Plan If you reach the included bundle units or monitored orders on the Free plan: - Processing stops for the remainder of the billing cycle (hard stop — no charges, no throttling) - Upgrade to a paid plan to resume processing immediately - Limits reset at the start of your next billing cycle ### Core and Ops Plans If you exceed the included bundle units or monitored orders: - BundlesIQ will notify you that you are approaching or have exceeded your plan limits - Processing may be paused or throttled for the remainder of the billing cycle - Upgrade to a higher plan to continue processing ### Scale+ Plan If you exceed the included limits on Scale+: - Overage charges are applied automatically (within your spending cap) - Processing continues uninterrupted - Usage and charges are visible in the app ## Cancellation To cancel your BundlesIQ subscription: 1. **Navigate** to **Shopify Admin > Settings > Apps and sales channels** 2. **Find** BundlesIQ 3. **Remove** the app (this also cancels the subscription) Or: 1. **Navigate** to **BundlesIQ > Billing** 2. **Click** **Cancel subscription** 3. **Confirm** the cancellation See [Disable or Uninstall BundlesIQ](/documentation/bundlesiq/uninstall-disable) for details on what happens to your data and orders. ## Related Pages - [Getting Started](/documentation/bundlesiq/getting-started) - [Disable or Uninstall](/documentation/bundlesiq/uninstall-disable) --- ### Uninstall # Disable or Uninstall BundlesIQ This guide explains how to safely stop BundlesIQ processing, disable specific features, or fully uninstall the app. ## Disable Processing (Without Uninstalling) If you want to stop BundlesIQ from processing orders temporarily while keeping your bundle configurations intact: ### Option 1: Disable Order Processing 1. **Navigate** to **BundlesIQ > Settings** 2. **Disable** **Process orders** and/or **Process draft orders** 3. **Click** **Save** BundlesIQ will stop processing new orders immediately. Existing bundles and configuration are preserved. ### Option 2: Deactivate All Bundles 1. **Navigate** to **BundlesIQ > Bundles** 2. **Open** each active bundle and **set** the status to **Inactive** 3. **Click** **Save** This stops BundlesIQ from detecting those specific bundles on orders while keeping the definitions for later reactivation. ### Option 3: Use Processing Scope 1. **Navigate** to **BundlesIQ > Settings** 2. **Set** the processing scope to **Tagged only** 3. **Leave** the include tags list empty 4. **Click** **Save** No orders will match the empty tag list, effectively pausing all processing. ## What Happens to Existing Orders When you disable processing: - **Already-processed orders** are not affected — their transformation remains in place - **Orders in progress** (currently being processed) will complete their transformation - **New orders** containing bundles will not be processed and will retain only the ghost SKU line item ## Uninstall BundlesIQ To fully remove BundlesIQ from your Shopify store: ### Before Uninstalling 1. **Verify** no orders are currently in the `BIQ_PROCESSING` state (check the Health dashboard) 2. **Consider** whether you need to keep the bundle processing tags on existing orders 3. **Note** that uninstalling removes the app's access and webhook subscriptions ### Uninstall Steps 1. **Navigate** to **Shopify Admin > Settings > Apps and sales channels** 2. **Find** BundlesIQ in the list 3. **Click** **Remove** 4. **Confirm** the removal ### What Gets Removed | Item | Removed on Uninstall? | |------|----------------------| | BundlesIQ app access to your store | Yes | | Webhook subscriptions | Yes — Shopify removes them automatically | | Order tags (`BIQ_PROCESSING`, `BIQ_READY`, `BIQ_ERROR`, `BIQ_REVERTED`) | No — tags remain on orders | | Order metafields (`bundles_iq.transformation_audit`) | No — metafields remain on orders | | Transformed order line items | No — component line items remain on orders | | Ghost SKU products | No — your Shopify products are not affected | | Bundle definitions in BundlesIQ | Preserved — available if you reinstall | | Shopify fulfillment holds | Released — any active holds placed by BundlesIQ are released during uninstall | ### What Gets Preserved - All previously processed orders remain in their transformed state - Ghost SKU products remain in your Shopify catalog - Order tags and metafields remain on orders - Your bundle configuration data is preserved in BundlesIQ's systems if you choose to reinstall later ## Cleaning Up After Uninstall ### Remove Tags (Optional) If you want to clean up BundlesIQ tags from existing orders: 1. In Shopify Admin, use the order filters to find orders with the `BIQ_READY` tag 2. Select orders in bulk and remove the tag 3. Repeat for `BIQ_PROCESSING`, `BIQ_ERROR`, and `BIQ_REVERTED` tags ### Remove Metafields (Optional) BundlesIQ order metafields (`bundles_iq` namespace) remain on orders after uninstall. These are not visible to customers and generally do not need to be removed. If you want to remove them: - Use the Shopify Admin API or a metafield management app to bulk-remove metafields in the `bundles_iq` namespace ### Ghost SKU Products After uninstalling BundlesIQ, your ghost SKU products remain in your catalog. You can: - **Keep them** if you plan to use BundlesIQ again or another bundle app - **Archive them** if you no longer sell bundles - **Delete them** if you are sure you will not need them (this is irreversible) > If you keep ghost SKU products active without a bundle app processing orders, customers can still purchase them. The order will contain only the ghost SKU without component expansion. Set ghost SKU products to **Draft** or **Archived** status if you want to prevent this. ## Reinstalling BundlesIQ If you reinstall BundlesIQ after uninstalling: - Your previous bundle definitions may be recoverable (contact support) - You will need to go through the onboarding process again - Previously processed orders will not be re-processed - You should run the [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) before processing real orders again ## Related Pages - [Global Settings Overview](/documentation/bundlesiq/global-settings) - [Go-Live Checklist](/documentation/bundlesiq/go-live-checklist) - [Billing and Plans](/documentation/bundlesiq/billing-plans) --- ### Changelog # Change Log All notable changes to BundlesIQ are documented here. Entries are listed newest first. --- ## June 2025 — Launch **Released: February 2026** BundlesIQ launches on the Shopify App Store. ### Features - **Four handling modes** — Hybrid, Reporting, Operational, and Parent-Only (BOM) modes for full control over how bundle orders are represented after processing - **Automatic order transformation** — Detects bundle orders and draft orders, expands them into component line items according to your selected mode - **Pricing allocation** — Distributes the bundle price across components using uniform percentage or per-component discount strategies - **Inventory sync** — Optionally derives bundle availability from component stock levels with configurable rules - **3PL protection** — Tags and holds orders during processing to prevent premature warehouse imports - **Draft order support** — Processes bundles in draft orders for B2B and wholesale workflows - **Health dashboard** — Real-time processing status, error flags, and lifetime statistics - **Multi-channel compatibility** — Works with online store, POS, Shop app, and third-party channels that create standard Shopify orders - **ShipStation integration** — Dedicated setup guide for ShipStation users