Product bundles and bundle groups
Learn when bundle work belongs to bundle groups, bundle records, bundle rules, store-group market availability, products, variants, or events.
Start here when products should be sold, merchandised, or synchronized together as a bundle, and you need to choose the right API surface before changing anything.
Use this page to choose the right bundle model before changing offer, bundle, rule, or availability data. For endpoint paths, request fields, response fields, status codes, and validation behavior, open the Product Bundles reference, Product Bundle Groups reference, or Bundle Rules reference.
The short model
A bundle group is the container for a bundle offer. It carries the group-level name, description, valid date range, and store-market availability that downstream systems receive in bundle events.
A product bundle is one bundle record inside a bundle group. Product bundle records carry the bundle status and discount configuration.
A bundle rule is a rule under a product bundle. Bundle rules describe the conditions and discount behavior that make the bundle work.
Choose the surface that matches the change:
- Use Product Bundle Groups when the grouping, valid date range, or store-group market availability changes.
- Use Product Bundles when one bundle record inside an existing group is created, read, updated, or deleted.
- Use Bundle Rules when rule records under one bundle need to be listed, created, read, updated, or deleted.
- Use Products, Variants, and Tags when the underlying catalog records or merchandising labels change outside the bundle.
- Use Events when another system needs to react after bundle or virtual-bundle changes.
Choose the right surface
Bundle work uses three reference hubs.
| Job | Use | Why |
|---|---|---|
| Inspect bundle groups | List Bundle Groups or Get Bundle Group | Bundle groups are the entry point for bundle grouping and availability. |
| Create, update, or remove a bundle group | Create Bundle Group, Update Bundle Group, or Delete Bundle Group | These operations change the group record, not an individual rule. |
| Add market availability for new work | Add Store Group Market to Bundle Group | New availability work should include store-group context. |
| Remove market availability for new work | Remove Store Group Market from Bundle Group | Use this when a bundle group should stop applying in one store-group market context. |
| Maintain older market-only integrations | Add Market to Bundle Group (Deprecated) or Remove Market from Bundle Group (Deprecated) | These routes remain visible for compatibility. Prefer store-group market routes for new work. |
| Create or inspect one bundle | Create product bundle or Get product bundle | Product bundle operations are scoped under a bundle group. |
| Update or delete one bundle | Update product bundle or Delete product bundle | Use these when the bundle record itself is changing. |
| Inspect bundle rules | List all bundle rules or Get a bundle rule | Bundle rules are nested under one product bundle. |
| Create, update, or delete a bundle rule | Create a bundle rule, Update a bundle rule, or Delete a bundle rule | Rule operations change bundle behavior without replacing the group or bundle record. |
For exact methods, paths, request bodies, response fields, enum values, and status codes, use the reference pages.
Contract facts to keep in mind
Use these facts to choose the right reference. Use operation pages for exact request fields, response fields, limits, status codes, and validation behavior.
- Product bundle status belongs to the product bundle record, not the bundle group. Current product bundle status values are
active,draft, andinactive. - Product bundle discounts are fixed or relative. Fixed discounts are stored as market-keyed minor-unit amounts, while relative discounts use a percentage.
- Bundle rules target product IDs and tag conditions, not variant IDs. Rules can reference explicit products, tag conditions, or both.
- Availability belongs to the bundle group. Store-group market operations should be the default for new availability work; older market-only routes remain for compatibility.
- Compliant bundle-group, product-bundle, rule, and availability writes publish
bundle.upsertwith the full bundle group. Bundle group deletion publishesbundle.delete.
MCP bundle-control
MCP can preview and apply bounded bundle-control work when an agent or operator needs a governed change flow instead of a direct API call. Use it for bundle group changes, market membership, product bundle changes, and bundle rule changes.
Bundle group creation checks for an existing group with the same name. Rule create and update previews require all referenced products to resolve and reject duplicate product IDs. Deletes and removals are destructive. They require explicit no-rollback acknowledgement before preview. Apply re-reads the preview assumptions, aborts when current evidence has drifted, writes through the matching bundle endpoint, and records audit evidence.
Product Bundle Groups, Product Bundles, and Bundle Rules reference pages still own exact endpoint paths, request fields, response fields, and status-code behavior.
Events
Use Events after bundle data changes. The Event catalog exposes bundle.upsert, bundle.delete, and virtual-bundle events for virtual bundle create, update, delete, product add, product remove, and product update.
Use the Event catalog for exact event type strings, schema IDs, required fields, and payload fields. Use Events latest for delivery and retry behavior.
Where to go next
- Need exact bundle-group operations? Use Product Bundle Groups reference.
- Need exact bundle operations? Use Product Bundles reference.
- Need exact rule operations? Use Bundle Rules reference.
- Need product and variant context? Read Products, variants, variant groups, prices, and stock.
- Need selling context? Read Store groups and markets.