Skip to main content

Create and query nested cart lines

Anchor to Creating nested cart linesCreating nested cart lines

You can add a nested cart line from a variety of Shopify APIs:

Anchor to Query for nested cart linesQuery for nested cart lines

Nested cart lines are represented across the following APIs:

Anchor to Create nested cart linesCreate nested cart lines

To create a nested cart line, specify a parent in the API input.

Anchor to Storefront APIStorefront API

Use the parent field in the cart mutation input. You can reference the parent by lineId (for existing line items in the cart) or merchandiseId (for adding both parent and nested cart lines in the same request).

  • Only one of lineId or merchandiseId should be used per line.
  • The response will return the nested cart line with a reference to its parent cart line under the parentRelationship object.

Example: Add TV and attach Warranty as an add-on

POST https://{shop}.myshopify.com/api/{api_version}/graphql.json

GraphQL mutation

mutation cartLinesAdd($cartId: ID!, $lines: [CartLineInput!]!) {
cartLinesAdd(cartId: $cartId, lines: $lines) {
cart {
lines(first: 10) {
edges {
node {
id
merchandise {
... on ProductVariant {
id
title
}
}
... on CartLine {
parentRelationship {
parent {
id
}
}
instructions {
canRemove
canUpdateQuantity
}
}
}
}
}
}
}
}

Variables

{
"cartId": "gid://shopify/Cart/1",
"lines": [
{
"merchandiseId": "gid://shopify/ProductVariant/1",
"quantity": 1
},
{
"merchandiseId": "gid://shopify/ProductVariant/2",
"quantity": 1,
"parent": {
"merchandiseId": "gid://shopify/ProductVariant/1"
}
}
]
}

JSON response

{
"data": {
"cartLinesAdd": {
"cart": {
"lines": {
"edges": [
{
"node": {
"id": "gid://shopify/CartLine/123",
"merchandise": {
"id": "gid://shopify/ProductVariant/1",
"title": "TV"
},
"parentRelationship": null,
"instructions": {
"canRemove": true,
"canUpdateQuantity": true
}
}
},
{
"node": {
"id": "gid://shopify/CartLine/456",
"merchandise": {
"id": "gid://shopify/ProductVariant/2",
"title": "1 year Warranty"
},
"parentRelationship": {
"parent": {
"id": "gid://shopify/CartLine/123"
}
},
"instructions": {
"canRemove": true,
"canUpdateQuantity": true
}
}
}
]
}
}
}
}
}

Anchor to Cart AJAX APICart AJAX API

You can reference the parent by specifying a parent_line_key (for existing line items in the cart) or parent_id (for adding both parent and nested cart lines in the same request) in the API input.

Notes:

  • Only one of parent_line_key or parent_id should be used per line.
  • The response will return the nested cart line with a reference to its parent cart line under the parent_relationship object.

Example: Add TV and attach a warranty as an add-on.

POST https://{shop}.myshopify.com/cart/add.js

Variables

[
{
"id": 1,
"quantity": 1
},
{
"id": 2,
"quantity": 1,
"parent_id": 1
}
]

JSON response

{
"items": [
{
"id": 1,
"properties": {},
"quantity": 1,
"variant_id": 1,
"key": "1:12345",
"title": "TV",
"product_title": "TV",
"variant_title": null,
"handle": "tv",
"requires_shipping": true
},
{
"id": 2,
"properties": {},
"quantity": 1,
"variant_id": 2,
"key": "2:56789",
"title": "Leash Warranty - 1 year",
"product_title": "Leash Warranty",
"variant_title": "1 year",
"parent_relationship": {
"parent_key": "1:12345"
},
"instructions": {
"can_remove": true,
"can_update_quantity": true
},
"handle": "tv-warranty",
"requires_shipping": true
}
]
}

Anchor to Checkout UI ExtensionCheckout UI Extension

Use the parent field in the addCartLine change that you pass to applyCartLinesChange. You can reference the parent by lineId or merchandiseId.

  • The parent field is available in API version 2025-10 and later.
  • applyCartLinesChange is available only to purchase.checkout extension targets, such as purchase.checkout.block.render.

Example: Add a warranty as an add-on to a product in the cart

Preact

import '@shopify/ui-extensions/preact';
import {render} from 'preact';

export default function extension() {
render(<Extension />, document.body);
}

function Extension() {
const warrantyVariantId = 'gid://shopify/ProductVariant/2';
const canAddCartLine =
shopify.instructions.value.lines.canAddCartLine;
const hasCartLines = shopify.lines.value.length > 0;

const handleNestWarranty = async () => {
// Read the latest lines, because cart line IDs can change after updates.
const lineId = shopify.lines.value[0]?.id;

if (!lineId) {
return;
}

const result = await shopify.applyCartLinesChange({
type: 'addCartLine',
merchandiseId: warrantyVariantId,
quantity: 1,
parent: {
lineId,
},
});

if (result.type === 'error') {
console.error(result.message);
}
};

return (
<s-button
onClick={handleNestWarranty}
disabled={!canAddCartLine || !hasCartLines}
>
Nest line
</s-button>
);
}

Anchor to Next stepsNext steps

Was this page helpful?