Preserving promotion eligibility through bundle transformation

Context

Ikigai Cases used promotions that depended on product meaning rather than a simple cart subtotal. The Free Nano offer could be an embedded gift in a bundle or a gift with purchase triggered by qualifying cases. A separate LABOR code made eligible engraving free.

Configurable products complicated both offers. Shopify could receive standalone merchandise, nested child lines, a merged parent, or an expanded parent depending on the product family. After transformation, the product that established eligibility or price might no longer be represented by a separate cart line.

My role

I implemented the promotion logic in two Shopify discount extensions and joined it to the Cart Transform and theme. I defined how bundle identities qualified, how conflicts were resolved, how engraving value survived a merge or expansion, and how the cart presented the resulting allocation.

I worked within the existing storefront and app foundations. Shopify Admin remained the control plane for campaign configuration, while I owned the commerce rules that decided which cart lines qualified and how those discounts survived transformation.

The actual challenge

A product title or discount code alone was too weak to decide eligibility. Nano items owned by a bundle needed to be distinguished from standalone Nano cases. Nested BYO and Monthly groups needed their parent relationship, logical slots, product identity, quantity, and offer rules checked before their children could qualify another promotion.

Engraving had the inverse problem. A merged Combined product absorbed engraving lines, while expanded MagNano and Magnetic Set products exposed their selected engraving through a parent payload. The LABOR Function needed an exact discount amount without trusting arbitrary values supplied by customers or discounting the whole configured product.

Offer precedence mattered too. Some promotions across the cart could not combine with Free Nano, and the bundle with two cases that already included a Nano could not also receive a manual Nano or combine with LABOR.

System design

I treated promotion eligibility as another consumer of the bundle protocol. The discount code or Function configuration selected a mode, but the cart structure determined whether a candidate was valid.

Free Nano had two explicit modes. Bundle mode targeted the gift already attached to a supported bundle. Gift with purchase mode found qualifying paid case lines and selected one eligible standalone Nano. LABOR had separate readers for a standalone engraving line, a merged Combined parent, and expanded MagNano and Magnetic Set parents.

Each reader returned no candidate when its contract was incomplete. Conflict rules were handled before candidates were emitted, and every accepted discount target carried a specific fixed amount or percentage rather than a general cart adjustment.

Classifying Free Nano eligibility

For nested BYO groups, I required one authorized carrier with a zero price, attached children with the same bundle identity, complete case slots, and allowed gift quantity. The free Nano child also had to match configured product identity and the eligibility signal for each variant. Ordinary BYO carriers could contribute paid case children to gift with purchase qualification; the carrier with two cases that already supplied a Nano was excluded.

Monthly qualification used its own contract. It checked the carrier, four numbered cases in the same size, allowed lid and pocket engraving identities, native relationships, physical shipping roles, and line prices. Only the validated case children became qualifiers.

For the manual offer, I filtered standalone Nano candidates by product identity, variant exclusion, price, and bundle ownership. I selected the cheapest eligible target and discounted one unit by its line amount. This prevented an internal bundle component or excluded variant from being mistaken for the promotional gift.

The orchestration also returned no Free Nano operation when conflicting LOVE or RETROMAG codes were present. In bundle mode it could reject a manually entered Free Nano code, and the bundle with an included Nano could reject LABOR according to the defined precedence.

Recovering engraving value

Standalone engraving lines were straightforward: the LABOR Function verified an engraving title, positive quantity, and positive value, then applied a full percentage discount to that line.

Merged Combined products required a handoff between Functions. Before merging, the Cart Transform identified eligible lid and pocket engraving lines, checked that their currencies agreed, summed their extended prices, and wrote a compact _ikg_labor amount on the merged parent. The discount Function accepted that amount only for a recognized merged marker, matching cart currency, positive subtotal, and a discount no larger than the line subtotal.

Expanded MagNano and Magnetic Set parents used a different authority. Their payloads identified engraving variants and configuration counts, while a catalog maintained in code mapped allowed variant, family, role, and Magnetic Set tier to base prices. The Function converted those trusted prices to presentment currency with configured rounding, checked the captured values where required, and calculated a fixed discount against the parent subtotal.

The catalog made hidden engraving prices explicit, but it also created a maintenance obligation. Product IDs, tier rules, and business prices had to remain synchronized with the storefront configuration.

Rendering and delivery behavior

The theme read Shopify discount allocations rather than recreating the discount decision in Liquid. When a line carried a LABOR allocation, bundle component rendering could label eligible lid and pocket engraving inside MagNano, Magnetic Set, and Combined presentations. The shared discount label rendered the actual application title.

Free Nano also included a delivery discount target. I scoped it to the first delivery group when the configured discount included the shipping class, keeping delivery behavior aligned with the offer configuration instead of inferring a broader rule across the cart.

Result

I delivered two explicit Free Nano modes and three transformed parent readers for LABOR, alongside the standalone engraving path. In September 2026, 101 Free Nano and 72 LABOR unit cases passed across valid offers, malformed groups, variant exclusions, promotion precedence, trusted engraving prices, currency branches, and invalid payloads.

The result was one promotion model that followed product identity through the cart instead of relying on whatever line shape happened to reach the discount Function. That made the offer rules testable across each supported bundle family and kept the cart presentation tied to Shopify's actual allocation.

Takeaway

When cart transformation changes product shape, promotions need an explicit identity and value handoff. Eligibility should come from validated relationships and trusted catalog rules, while presentation should follow the discount Shopify actually allocated. That keeps a promotion specific even when the original merchandise lines are no longer visible.