Payments

Migrating Shopify Subscriptions to SubscriptionContractCalculation Before API 2026-10

Shopify adds SubscriptionContractCalculation on GraphQL Admin API 2026-10 as the successor to SubscriptionDraft. Autoship apps should retest tax, payment methods, and commit handling before the stable cutover.

E-commerce 4 Internet Marketers Editorial

Illustration of two developers comparing subscription contract notes outdoors at a Northeastern park picnic table in late September light.

By E-commerce 4 Internet Marketers Editorial

Shopify’s GraphQL Admin API introduces SubscriptionContractCalculation as the successor to SubscriptionDraft for creating, updating, and editing subscription contracts. The object is available in early access on the 2026-10 release candidate and becomes part of the stable 2026-10 surface on October 1, 2026, according to Shopify’s July 27, 2026 changelog and 2026-10 release notes.

For supplement, CBD, telehealth, and other autoship brands, recurring billing is operational risk. Apps that still edit contracts through the multi-step draft workflow should learn the new calculate, poll, commit lifecycle before they need a capability that only exists on the checkout-aligned calculation path.

What changes from SubscriptionDraft

Shopify’s migration guide contrasts the two models. SubscriptionDraft is a multi-step, synchronous workflow. The server holds draft state while the app calls a long sequence of mutations (create draft, add or update lines, apply discounts, update delivery, then commit).

SubscriptionContractCalculation is asynchronous and largely stateless from the app’s point of view. The client submits the desired contract state in one calculate mutation. Shopify runs pricing, taxes, discounts, and supported Shopify Functions through the same C1 checkout engine used for Checkout, Draft Orders, and subscription billing attempts, then returns an immutable snapshot. On updates, omitted fields stay unchanged, so the app does not have to resend the entire contract.

Shopify’s early-access changelog says one calculate mutation replaces more than a dozen draft mutations, and that both APIs can coexist while teams migrate incrementally. Status changes (activate, pause, cancel, expire, fail) stay on dedicated mutations and are not set through the calculation input.

The calculate, poll, commit lifecycle

Shopify documents three calculate entry points plus a shared commit:

  • subscriptionContractCreateCalculate for a new contract.
  • subscriptionContractUpdateCalculate for changes to an existing contract.
  • subscriptionBillingCycleContractEditCalculate for a one-time edit to a single billing cycle.
  • subscriptionContractCalculationCommit to persist a successful calculation.

After calculate, the response is typically SubscriptionContractCalculationPending. Apps either poll the subscriptionContractCalculation query or subscribe to the subscription_contract_calculations/succeed and subscription_contract_calculations/fail webhooks until the result is SubscriptionContractCalculationSuccess or SubscriptionContractCalculationFailure. Only then should the app call commit.

Shopify’s migration guide recommends waiting about one second before the first poll, polling about every 500 milliseconds, and timing out after roughly 30 seconds or on failure. Uncommitted calculations are deleted after seven days. Retrying calculate creates a new calculation ID. Retrying commit on an already committed result returns success.

Feature flags matter for regulated catalogs that use bundles or delivery rules. The top-level withMerchandiseCustomizations Boolean controls cart transforms and related merchandise Functions. On delivery option discovery, withDeliveryCustomizations (default true) controls whether delivery customization Functions reshape the option list.

Mapping common draft mutations

Shopify publishes an explicit mutation map. Examples include subscriptionContractCreate and subscriptionContractAtomicCreate mapping to subscriptionContractCreateCalculate; subscriptionContractUpdate and subscriptionContractProductChange mapping to subscriptionContractUpdateCalculate; line add/update/remove becoming entries in a lines[] array (omit a line to remove it); discount-code apply moving to discountCodes[]; order and free-shipping discounts moving into manualDiscounts[] as orderDiscount or deliveryDiscount; and draft commit mapping to subscriptionContractCalculationCommit.

Some draft behaviors are relocated rather than deleted. Contract status is no longer set on the draft input. Line pricingPolicy is renamed appManagedPricingPolicy and is not used during calculation. nextBillingDate, minCycles, and maxCycles move under appManagedBillingConfig. Multi-fulfillment for pre-paid subscriptions becomes an explicit multiFulfillment configuration when needed.

One gap remains. Shopify states that subscriptionBillingCycleContractDraftConcatenate has no calculate API equivalent yet, so apps that concatenate billing-cycle drafts should keep using the draft API for that step.

Why autoship and specialty payment stacks should retest

Because calculation runs through the unified checkout engine, projected totals (subtotal, delivery, tax, merchandise discounts, delivery discounts, grand total) and delivery options can differ from what a draft-based integration assumed. Address changes, destination-based tax, and delivery customization Functions are the surfaces Shopify highlights as newly aligned with checkout.

Merchants that combine Shopify subscription contracts with an external gateway for specialty acquiring (for example Authorize.Net or NMI on a separate MID) still need their own regression suite. Shopify’s docs do not prescribe how a third-party gateway should react when a contract payment method is swapped or when a calculation fails. Teams should retest payment-instrument update emails, declines, and refusal handling against the poll and commit path, and confirm that tax on projected order totals matches what the storefront and the processor expect before BFCM volume.

Shopify also warns not to build production integrations on the early-access surface until 2026-10 is stable. The draft object will be deprecated once the calculation API reaches general availability on 2026-10. It remains available afterward but will not gain the new checkout-aligned capabilities.

Practical migration checklist

  • Pin a staging app to Admin API 2026-10 and confirm the write_own_subscription_contracts scope.
  • Inventory every write path that touches SubscriptionDraft (create, update, billing-cycle edit, discount, delivery).
  • Rebuild those paths as calculate, then poll or webhook, then commit, retaining calculation IDs until commit succeeds.
  • Retest tax, delivery options, bundle expansion, and payment-method swaps on real contract fixtures, including failed calculations.
  • Keep concatenate-only flows on the draft API until Shopify ships a calculation equivalent.
  • Schedule the production cutover for after October 1, 2026 stability unless Shopify documents an earlier production-ready exception for the shop.

Closing

SubscriptionContractCalculation replaces the stateful SubscriptionDraft edit loop with a checkout-aligned calculate, poll, commit workflow on GraphQL Admin API 2026-10. Autoship operators and subscription app developers should migrate for the new capabilities, keep the draft API only where Shopify still requires it, and finish tax, delivery, and payment-instrument regression tests before the October 1, 2026 stable cutover rather than during peak holiday traffic.

Sources