Priced Bundle Data in Orders and Returns

A priced bundle consists of these lines:

• The bundle item is the priced line that represents the bundle as a whole.
• The bundle components are the individual products that the bundle contains.

Fields Used for Grouping

Group priced bundles by using these fields.

To find the bundle item in a group of lines that share a productBundleId, look for the line whose productId equals that value. Don't rely on position. The remaining lines in the group are its components.

Pricing of Bundle Lines

All pricing for a priced bundle lives on the bundle item line. Its price, subTotal, tax, and total represent the whole bundle. Each component line carries 0 for all four fields.

To read a bundle's monetary value, take it from the bundle item line. Don't sum the component lines. They contribute 0.

Note Some downstream systems expect only component lines, each carrying its own share of the price, with no separate bundle item line. Priced bundles in Point of Sale don't work this way, and no configuration changes it: the bundle item line always carries the full price, and component lines always carry 0. Any downstream system that consumes this data must handle the bundle item line together with its components.

Grouping Bundles in an Order

Group lines by productBundleId and bundleGroupId. Lines sharing both values belong to the same bundle instance. The same bundle can appear more than one time in an order, so each instance needs its own bundleGroupId value.

Data Exposed on Returned Lines

Returned lines carry the same bundle fields as order lines: productBundleId, bundleGroupId, and orderItemId, plus a transactionId.

• productBundleId and bundleGroupId keep their original order values, so a returned line ties back to its bundle.
• orderItemId matches the orderItemId of the original order line.
• transactionId identifies a single return event. All lines returned together share one value, and a later return of the same bundle gets a different one. Because bundleGroupId doesn't change across returns, transactionId is what distinguishes separate return events.

Returned lines within each transactionId appear in ascending orderItemId order: the bundle item first, followed by its components.

Treat Each Item as a Separate Line Item Setting

This setting controls how repeated bundles or bundle components appear as lines and quantities. Turn this setting on or off in Store Management | Store Settings | OMS | Advanced, by using the Treat Each Item As Separate Line Item toggle.

false (default): quantities are aggregated

• Repeated purchases of the same bundle merge into one bundle group, with quantities summed. A component repeated within the bundle is still a single-line, with its quantity reflecting the total count.
• Each line's quantity is independent, so a component's quantity can be greater than 1 even when it doesn't equal the bundle items.
• Example: A bundle bought twice appears as one group (bundleGroupId "1") with the bundle item at quantity 2, one component line at quantity 4, and other component lines at quantity 2.

true: each unit is its own line

• Each purchased bundle instance becomes its own bundle group, and every line in it has quantity 1.
• A component repeated within the bundle appears as multiple separate lines with the same productId, each at quantity 1.
• Example: A bundle bought twice appears as two groups (bundleGroupId "1" and "2"). Each group has the bundle item (quantity equal to 1) followed by its component lines (quantity equal to 1 each). A component included twice in the bundle shows as two separate lines, each with quantity equal to 1.

Don't assume a component's quantity equals the bundle item's quantity, and don't assume a productId is unique within a bundle group.