Edit subscription contracts with bundles

A subscription contract can contain bundle products. This guide explains how a bundle is represented on a contract, how pricing is allocated between a bundle parent line and its component lines, and how to add, update, and remove bundles when you update a subscription contract with the SubscriptionContractCalculation API.

Anchor to RequirementsRequirements

• Your app can make authenticated requests to the GraphQL Admin API.
• Your app has the read_own_subscription_contracts and write_own_subscription_contracts access scopes. Learn how to configure your access scopes using Shopify CLI.
• You've created products and product variants in your development store.

• Use the GraphQL Admin API version 2026-10 or later.
• Familiarize yourself with updating a subscription contract, including the calculate, poll, and commit flow.

Anchor to How bundles appear on a contractHow bundles appear on a contract

A contract exposes its lines in two ways:

• lines: A flat connection. Every sellable line has an entry, including each component of a bundle as its own SubscriptionLine.
• groupedLines: A grouped connection of SubscriptionGroupedLine values. A standalone line is returned as a SubscriptionLine. A bundle is returned as a SubscriptionParentLine with its component lines nested under components.

A component's membership in a bundle is expressed structurally by its position under a parent node in groupedLines. Component lines don't carry a flat back-reference to their parent, so use groupedLines whenever you need the bundle structure.

The SubscriptionParentLine type describes the bundle parent:

The following query returns both views of the contract's lines:

Anchor to PricingPricing

Pricing for a bundle lives on its component lines:

• Each component line carries its own unit price (currentPrice) and discounted total (lineDiscountedPrice).
• The bundle parent line doesn't have an independent price. Its value is the per-bundle-unit sum of its component prices.
• When you supply a custom bundle, each component's priceOverride sets that component's unit price. Components without an override use the price that Shopify calculates for them.
• The parent line's quantity multiplies each component's quantity. A bundle with quantity 3 that contains a component with quantity 2 results in a component line with quantity 6. Component unit prices aren't multiplied.

Discounts apply to component lines the same way they apply to standalone lines. For how to apply discount codes, order and delivery discounts, and line-scoped discounts during a calculation, refer to Manage discounts.

Anchor to Editing behaviorEditing behavior

Bundle handling during a contract edit is controlled by the required withMerchandiseCustomizations field on the calculate input, which determines whether merchandise transformations run during the calculation: both fixed bundle expansion from a stored definition and Shopify Functions that customize merchandise, such as cart transforms. The following table summarizes how each line input behaves when customizations are enabled (true) or disabled (false):

As with any contract update, the lines array replaces the complete collection. Include every line that you want to keep, and omit the lines that compose a bundle to remove the bundle and all of its components. See Update or remove a bundle to learn more.

Anchor to Add an expanded or merged bundleAdd an expanded or merged bundle

Shopify composes bundles during calculation in the following ways:

• Expand: A bundle parent variant is expanded into its component lines, from a fixed bundle definition (BUNDLES_STATIC_EXPAND) or a cart transform function's expand operation (BUNDLES_DYNAMIC_EXPAND).
• Merge: Separate lines are merged into a single bundle by a cart transform function's merge operation (BUNDLES_DYNAMIC_MERGE).

To add a bundle that expands, supply the bundle's parent product variant as a regular productVariantLine and set withMerchandiseCustomizations: true. The calculation expands the parent into its component lines and applies the bundle's pricing:

If you supply a bundle parent variant this way with withMerchandiseCustomizations: false, then the mutation returns a user error: Product variants that require components can't be supplied as standalone product variant lines. Provide components or set withMerchandiseCustomizations: true.

To add a bundle that merges, supply each line that the shop's cart transform function merges as its own productVariantLine and set withMerchandiseCustomizations: true. During calculation, the function merges the matching lines into a bundle parent line with its components nested under it. Unlike a bundle parent variant, these lines are ordinary sellable variants: if you supply them with withMerchandiseCustomizations: false, then they're accepted but remain standalone lines, and no bundle is composed.

Anchor to Add a custom bundleAdd a custom bundle

To control a bundle's composition yourself, add a custom bundle: supply a productVariantParentLine with the parent variant and an explicit list of components, and set withMerchandiseCustomizations: false. Shopify stores the composition exactly as provided and never rebuilds it from the bundle's definition:

The productVariantParentLine input accepts the following fields:

If you supply a productVariantParentLine with withMerchandiseCustomizations: true, then the mutation returns a user error: Source-provided bundles are only supported with withMerchandiseCustomizations: false. API messages and the sourceType value refer to custom bundles as source-provided.

Anchor to Update or remove a bundleUpdate or remove a bundle

Because lines replaces the complete collection, editing a bundle means restating it:

• Update a custom bundle: Include the parent line's id and the complete desired components list. The supplied components replace the bundle's existing components, and their quantities are per bundle unit.
• Update an expanded or merged bundle: With withMerchandiseCustomizations: true, restate the lines that compose the bundle along with your other changes: the bundle's parent variant line for a bundle that expands, or the individual lines that the function merges for a bundle that merges. The calculation rebuilds the bundle from its current definition.
• Remove a bundle: Omit the lines that compose the bundle from lines: the bundle's parent line for a bundle that expands, or the lines that the function merges for a bundle that merges. The parent and all of its component lines are removed. Components can't be removed individually from an expanded or merged bundle, because the composition comes from the bundle's definition.

Anchor to Keep existing bundles unchangedKeep existing bundles unchanged

To edit other parts of a contract without recalculating its bundles, omit the lines field and set withMerchandiseCustomizations: false. The stored bundle structure, including component quantities and unit prices, is preserved exactly.

Omitting lines isn't sufficient on its own: when lines is omitted with withMerchandiseCustomizations: true, stored expanded and merged bundles are rebuilt from their current definitions instead. If the contract contains a custom bundle, this returns a user error: The contract has a custom bundle that cannot be re-derived. Set withMerchandiseCustomizations: false to preserve the stored bundle.

Anchor to Review the calculated bundle structureReview the calculated bundle structure

After calculating, poll the calculation and query groupedLines on the calculated contract to verify the bundle structure before committing:

Then commit the calculation as described in Update a subscription contract.

Anchor to ConsiderationsConsiderations

• Lines replacement: The lines array replaces all existing lines. Omitting the lines that compose a bundle removes the bundle and its components. For a bundle that expands, omit its parent line. For a bundle that merges, omit the lines that the cart transform function merges.
• Custom bundles are never rebuilt: A custom bundle always calculates with withMerchandiseCustomizations: false, both when you restate it and when you omit lines on a later edit.
• Deleted components: If a component variant was deleted from the catalog, then an edit with withMerchandiseCustomizations: false preserves the stored component as a customLine without a variant, while an edit with withMerchandiseCustomizations: true rebuilds the bundle from its current definition, which drops the deleted component.
• Deleted bundle parent variants: If a stored bundle's parent variant no longer exists, then a calculation with withMerchandiseCustomizations: true fails with an error that suggests supplying replacement lines or setting withMerchandiseCustomizations: false to preserve the stored bundle.
• Partial bundle subscriptions: Contracts created from a selling plan that covers only some bundle components store those components as standalone lines. They have no parent line, and you edit them as regular product variant lines.

Anchor to TerminologyTerminology

Anchor to Next stepsNext steps

• Learn how to update a subscription contract, including the full calculate, poll, and commit flow.
• Refer to the SubscriptionContractCalculationLineInput and SubscriptionParentLine reference documentation.