Shopify SubscriptionContractCalculation API: subscription changes

Shopify API 2026-10 introduces SubscriptionContractCalculation for creating and modifying subscription contracts. It replaces the older SubscriptionDraft approach for create and update operations and runs calculations through Shopify's checkout engine.

The important change is the workflow, not the GraphQL object's name. Before persisting a contract update, an app can obtain a complete calculation, inspect totals, delivery options, warnings and Shopify Functions results, and only then decide whether to commit.

What changes with SubscriptionContractCalculation?

The new workflow has three main stages: calculate, poll and commit. The app submits the desired contract state, Shopify calculates the result asynchronously, the app waits for that result and finally commits the change.

Shopify describes this API as the successor to SubscriptionDraft. The older object remains available but will not receive the new capabilities added to this model. Apps that modify subscription contracts should therefore plan a migration when adopting API 2026-10.

Why this flow is different from the old draft

Calculations no longer run in a separate engine. Shopify evaluates the proposed change through its checkout engine and returns an immutable preview before persistence.

That can reduce a particularly sensitive subscription failure mode: the technical outcome of a contract modification differing from what the customer is later charged in a billing cycle.

The new API also consolidates several operations previously spread across separate mutations. Use subscriptionContractCreateCalculate to create a contract, subscriptionContractUpdateCalculate to update it, and subscriptionBillingCycleContractEditCalculate to modify an individual billing cycle. The calculated result is then verified and persisted through subscriptionContractCalculationCommit.

Bundles and Shopify Functions for recurring contracts

A significant addition is support for bundle products in subscription contracts. The calculation can also account for Shopify Functions such as cart transforms and delivery customizations.

This does not automatically make every subscription business model simple. It does address structural limitations that made consistency between checkout and renewals more difficult.

App developers should test more than whether a mutation returned successfully. Verify the calculated values, warnings, delivery options and totals, then read back the persisted contract after the commit.

The calculate → poll → commit workflow

A practical sequence is:

1. Calculate. Send Shopify the desired contract state or the changes permitted by the operation.
2. Poll. Wait for the asynchronous calculation to succeed or fail. Shopify also provides dedicated webhooks reporting calculation outcomes.
3. Validate. Inspect the result before persistence: line items, prices, discounts, delivery, taxes, duties where applicable and warnings.
4. Commit. Persist the calculation only after application-specific checks pass.
5. Read back. Fetch the resulting contract and verify its actual downstream behaviour rather than relying on the mutation's positive response.

This matches the verification discipline applied to Shopify integrations generally: an accepted API write is not proof that the final behaviour is correct.

Which apps actually need to migrate?

The main impact is on apps that create, update or modify subscription contracts through SubscriptionDraft. Apps that only read contracts, or change their status through dedicated mutations such as activation and pause, are not affected in the same way.

This should not be confused with a blanket change to Shopify's native Subscriptions app. Merchants looking for functional limits and use cases can consult the IFG guide to Shopify Subscriptions and recurring payments. The focus here is the API architecture of apps that manage contracts.

What to check when migrating from SubscriptionDraft

Start by listing the draft mutations the integration currently uses and identifying which values the app assumes are final. Then review at least four areas.

First, asynchronous processing: a calculation result must not be treated as immediately available. Second, data mapping: the new calculation object and preview become the data to validate before the commit. Third, test coverage for Shopify Functions, bundles and delivery where the business model depends on them. Fourth, post-commit readback and failure cases: the contract should remain in a known, recoverable state.

For the broader version upgrade, combine this assessment with the other checks in Shopify API 2026-10: what to verify before upgrading an integration.

What this means for merchants and technical teams

A merchant using an existing subscription app does not need to perform a manual migration in Shopify Admin. The technical responsibility rests with the app managing the contracts.

But the quality of that migration can affect renewal prices, bundles, delivery, discounts and transformations applied during recurring cycles.

Avoid blind upgrades. This API offers a more robust model precisely because calculation and persistence are separate. Use that separation to add validation rather than recreating the old flow under new names.

Shopify sources

• Shopify Developer Changelog: New SubscriptionContractCalculation API for subscription management
• Shopify.dev: About subscription contracts
• Shopify.dev: Update a subscription contract