Nested cart lines

Nested cart lines let you define parent-child relationships between items in the cart, checkout and order. This enables use cases like product add-ons (warranties, protection plans, service fees) that attach to a product in cart. For example, you might attach an extended warranty to a TV. Unlike regular cart lines, nested cart lines are always ordered after their parent line, and are removed from cart if parent is removed. Additionally, a variant cannot nest under itself as it is considered a circular reference.

Nested relationships can be created through Shopify's Cart APIs and Checkout UI extension API, and Shopify renders them throughout the entire buyer and merchant journey. This provides buyers with a clear view of the relationship throughout their journey (cart, checkout, and post-purchase surfaces such as order confirmation emails and order status pages).

Anchor to How it worksHow it works

1. Your app creates the nested relationships by calling the Storefront, Cart AJAX or Checkout UI Extension API.
2. Shopify will then take that and honour it across the following surfaces where applicable:

• Buyer Facing:
  • Cart (Horizon and Dawn based themes)
  • Checkout and Thank you Page
  • Order Status page
  • Order related and abandoned checkout emails
• Merchant Facing:
  • Admin Abandoned Checkout
  • Admin Order details

Anchor to LimitationsLimitations

Nested cart lines work automatically throughout the platform, except in these areas:

• Bundles: You cannot nest add-ons under bundle parents or components at this time.
• Draft Orders: Creating nested cart lines via the draft order API.
• Immutable: Once set, a nested cart line's parent relationship cannot be modified.
• Multi-level nesting: Only one level of parent-child is allowed.
• Order Editing: Creating nested cart lines via Order Editing.
• Accelerated checkout buttons: Not compatible with nested lines creation from product pages
• POS: Creating nested cart lines in POS.
• Scripts: Not supported - when the script editor app is installed, nested relationships cannot be created.

Anchor to CartTransform operations on nested cart linesCartTransform operations on nested cart lines

CartTransform operations on nested cart lines have the following behaviors:

• When lineUpdate is applied to a parent or child in a nested relationship:
  • The update is applied.
  • The nested relationship is preserved.
• When linesMerge is applied to a parent or child in a nested relationship:
  • The lines aren't merged.
  • The cart is unchanged.
• When lineExpand is applied:
  • On parent line:
    • The parent is expanded.
    • Its child lines are removed from the cart.
  • On a child nested line:
    • The operation runs and the child's presentation can change according to the arguments passed to lineExpand.
    • The parent/child relationship remains.

Anchor to Next stepsNext steps

• Learn how to create and query nested cart lines