ParcelPilot
Help

Client Integrations — Virtual Bundle Stock Sync

Use this guide when an ecommerce integration should receive a derived stock quantity for a virtual bundle parent SKU.

Overview

Virtual bundle stock sync allows ParcelPilot to push a derived stock quantity for a bundle parent SKU in supported ecommerce integrations.

This is intended for channels where:

  1. the channel has a normal stock-managed parent SKU
  2. ParcelPilot knows the bundle structure from items.attributes.bundle
  3. ParcelPilot should calculate the parent quantity from component availability
  4. orders for the parent SKU are still fulfilled from ParcelPilot component items

This feature is default-off and must be enabled per integration.

This guide is about outbound stock quantities only. Bundle shipping-weight calculation is configured on the item record separately and does not widen the stock-sync support rules in this article.

What It Does

When enabled, ParcelPilot can include virtual bundle parent SKUs in stock sync payloads.

The pushed parent quantity is calculated from the lowest currently buildable quantity across the bundle components.

ParcelPilot does not create a separate physical stock bucket for the bundle parent.

When a component stock mutation propagates after commit, ParcelPilot keeps the direct component SKUs in scope and can fan out that same push to dependent bundle parent SKUs for integrations where the bundle sync policy is enabled.

When To Enable It

Enable virtual bundle stock sync only when all of the following are true:

  1. the ecommerce channel expects a normal stock-managed parent SKU
  2. the parent SKU should reflect ParcelPilot-derived component availability
  3. stock_sync_enabled is already on for the integration
  4. stock_master is set to ParcelPilot
  5. the bundle structure is a fixed virtual bundle, not a dynamic or physical bundle
  6. fulfilment should continue to reserve and deduct component items only

When To Leave It Disabled

Leave the setting disabled when any of the following apply:

  1. the channel should not receive derived parent quantities
  2. the channel or plugin manages bundle inventory in its own way
  3. the parent SKU is not a normal stock-managed SKU in the channel
  4. the bundle structure is nested, hybrid, dynamic, or otherwise unsupported
  5. you are not yet ready to validate end-to-end bundle stock behaviour with a controlled test integration

How Derived Quantities Are Calculated

ParcelPilot calculates bundle availability from the component sellable quantities.

Component sellable quantity:

$$ \text{component sellable} = \max(0, \sum qty - \sum reserved) $$

Bundle buildable quantity per component:

$$ \text{buildable from component} = \left\lfloor \frac{\text{component sellable}}{\text{qty per bundle}} \right\rfloor $$

Final bundle quantity:

$$ \text{bundle quantity} = \min(\text{buildable from each component}) $$

ParcelPilot excludes:

  1. DISCONTINUED inventory units
  2. inventory in QUARANTINE locations
  3. inventory in RETURNS locations

Worked Examples

Example 1: Simple 1:1 Kit

Bundle parent:

  • KIT-001

Components:

  • COMP-A x1
  • COMP-B x1

Stock:

  • COMP-A = 9
  • COMP-B = 10

Derived bundle quantity:

  • KIT-001 = 9

Reason:

  1. COMP-A can build 9 kits
  2. COMP-B can build 10 kits
  3. the lowest buildable quantity is 9

Example 2: Uneven Component Ratio

Bundle parent:

  • KIT-002

Components:

  • COMP-A x3
  • COMP-C x1

Stock:

  • COMP-A = 9
  • COMP-C = 7

Derived bundle quantity:

  • KIT-002 = 3

Reason:

  1. COMP-A can build floor(9 / 3) = 3
  2. COMP-C can build floor(7 / 1) = 7
  3. the lowest buildable quantity is 3

Example 3: Policy Disabled

If the integration keeps virtual bundle stock sync disabled:

  1. ParcelPilot still pushes direct component SKUs
  2. ParcelPilot does not include bundle parent SKUs in full or targeted stock payloads

Supported Bundle Structures

Supported in Phase 2A:

  1. fixed virtual bundles
  2. deterministic component lists on the item record
  3. positive numeric item_id and qty values
  4. multiple valid parent bundles sharing one component
  5. parent SKUs fulfilled from component items only

Unsupported Bundle Structures

Not supported in Phase 2A:

  1. nested bundles
  2. self-referential bundles
  3. bundle cycles
  4. missing component items
  5. missing component ids
  6. non-positive component quantities
  7. physical bundle stock
  8. hybrid bundle stock
  9. platform-native dynamic bundle modelling

Unsupported bundle parents are skipped safely during stock sync.

Shipping Weight Note

ParcelPilot can now auto-calculate a bundle parent's shipping weight from component item weights in item and shipment flows.

That is independent of virtual bundle stock sync:

  1. shipping-weight auto-calculation is configured per item
  2. stock-sync enablement is configured per integration
  3. nested bundles may be resolved for shipping weight even though nested bundles remain unsupported for Phase 2A stock-sync payloads

Integration Setting Location

Location in the admin UI:

  1. open Client Integrations
  2. open the target ecommerce integration
  3. go to the ecommerce settings section
  4. enable Enable stock sync if required
  5. set Stock master to ParcelPilot
  6. enable Enable virtual bundle parent stock sync

Stored setting:

  • settings.bundle_stock_sync.enabled

Default-Off Behaviour

This feature is intentionally default-off.

That means:

  1. new integrations start with the setting disabled
  2. older integrations that do not yet have the setting also behave as disabled
  3. bundle sync is never activated implicitly by parser, payload, or propagation logic

Rollout And Rollback Guidance

Recommended rollout:

  1. enable the setting for one test integration only
  2. validate one targeted component stock change and one full stock sync
  3. confirm the parent SKU quantity matches the derived expectation in the channel
  4. confirm order fulfilment still reserves and deducts component items only

Recommended rollback:

  1. turn off Enable virtual bundle parent stock sync
  2. rerun a full stock sync for the affected integration so the outbound payload returns to direct-SKU-only behaviour
  3. keep the local bundle definition unchanged unless the bundle itself is no longer operationally valid

Rollback does not require changing order fulfilment, reservation, or deduction logic because Phase 2A is additive and default-off at the integration layer.

Platform Notes

Shopify

  1. use only when the parent SKU is a normal stock-managed Shopify SKU
  2. ParcelPilot does not implement Shopify-native bundle-app logic in Phase 2A
  3. fulfilment still happens from ParcelPilot component items

WooCommerce

  1. use only when the parent SKU is a normal stock-managed WooCommerce SKU
  2. Woo bundle plugins and custom bundle inventory logic are outside Phase 2A scope
  3. keep the setting disabled if Woo is expected to own bundle inventory logic

Magento

  1. Magento supports full sync, targeted multi-SKU sync, and the current single-SKU push path
  2. use only for simple stock-managed parent SKUs
  3. Magento native dynamic bundle semantics are out of scope
  4. the existing Magento quantity-only stock option remains separate from this feature

BigCommerce

  1. use only when the parent SKU is a normal stock-managed BigCommerce SKU
  2. BigCommerce-specific bundle apps or custom bundle logic are outside Phase 2A scope
  3. keep the setting disabled if BigCommerce should remain the source of truth for bundle handling

Troubleshooting

Bundle Parent Not Appearing In Stock Push

Check:

  1. Enable stock sync is on
  2. Stock master is ParcelPilot
  3. Enable virtual bundle parent stock sync is on
  4. the bundle definition is enabled on the item
  5. all component rows have valid item_id and positive qty
  6. component items belong to the same tenant and client
  7. the bundle is not nested or cyclic

Bundle Parent Quantity Looks Too Low

Check:

  1. component reserved stock levels
  2. whether the limiting component has a higher quantity-per-bundle ratio
  3. whether some inventory is in QUARANTINE or RETURNS
  4. whether some inventory units are DISCONTINUED
  5. whether a warehouse scope is restricting sellable stock

Direct Components Push But Parent Does Not

This usually means one of the following:

  1. bundle sync policy is disabled for the integration
  2. the parent bundle definition is invalid or unsupported
  3. the parent SKU is not part of a valid fixed virtual bundle structure

Single Bundle SKU Push Returns Zero

Current Phase 2A behaviour:

  1. Magento single-SKU pushes return the derived quantity only when bundle sync is enabled
  2. when bundle sync is disabled, the direct parent path remains safe and currently resolves to zero because there is no separate parent stock bucket

Validation Checklist

Before enabling this for a live integration:

  1. confirm the bundle parent SKU exists in the channel as a standard stock-managed SKU
  2. confirm the ParcelPilot item bundle definition is enabled and valid
  3. confirm component stock values are easy to predict for the test
  4. enable stock sync and set stock master to ParcelPilot
  5. enable virtual bundle parent stock sync for one test integration only
  6. run a targeted component stock change and confirm the parent SKU is included
  7. run a full stock sync and confirm the parent SKU quantity matches the derived expectation
  8. if Magento is used, run a direct single-SKU push for the bundle parent and confirm the derived value
  9. confirm fulfilment logic still reserves and deducts components, not the parent

Support Checklist

When assisting a client or operator:

  1. capture the integration platform and integration id
  2. capture whether stock sync is enabled and whether ParcelPilot is stock master
  3. capture the bundle sync setting state
  4. capture the parent SKU and component SKUs
  5. capture the expected derived quantity and the actual pushed quantity
  6. capture whether the issue is full sync, targeted sync, or single-SKU push
  7. review whether any component is missing, reserved, discontinued, quarantined, or in returns
  8. review whether the bundle structure is nested, cyclic, or otherwise unsupported
  9. check recent sync logs or integration events for skipped or reduced payloads

Related Guides