Skip to main content
Back to changelog

SubscriptionContractCalculation API now available in early access

The new SubscriptionContractCalculation object on the GraphQL Admin API is now available in early access on the 2026-10 release candidate API version. It's the successor to the GraphQL Admin API's SubscriptionDraft object for creating, updating, and editing subscription contracts, replacing the multi-step draft workflow with a stateless calculate → poll → commit lifecycle that runs through Shopify's unified checkout engine.

Moving contract edits onto the unified checkout engine keeps calculations consistent with checkout, one calculate mutation replaces 12+ draft mutations, and new checkout capabilities work with contract edits without waiting on subscriptions-specific support. This affects any app that manages subscription contracts. If you build on subscriptions, you'll need to migrate to the new API to gain its new capabilities, but you can migrate incrementally, since both APIs will coexist.

Who's affected

This applies to any app that creates, updates, or edits subscription contracts using the SubscriptionDraft object. Apps that only read contracts or manage contract status (through subscriptionContractActivate, subscriptionContractPause, and similar mutations) are unaffected. Status is still set through those dedicated mutations, not the calculation input.

The API is now available on the 2026-10 release candidate API version for early access and becomes stable on 2026-10.

What changed

Contract edits now run through the same C1 checkout engine that powers Checkout, Draft Orders, and subscription billing attempts, instead of the bespoke SubscriptionDraft engine that ran in parallel to checkout.

The previous workflow required a dozen-plus stateful mutations across the draft lifecycle to edit a single contract (create draft → add line → update line → remove line → add discount → apply code → update delivery → commit). The new API consolidates this into three calculate operations plus a shared commit:

  1. Calculate: submit the desired contract state in a single mutation: subscriptionContractCreateCalculate, subscriptionContractUpdateCalculate, or subscriptionBillingCycleContractEditCalculate.
  2. Poll: the calculate mutation returns a SubscriptionContractCalculationPending response. Poll the subscriptionContractCalculation query, or subscribe to the subscription_contract_calculations/succeed and subscription_contract_calculations/fail webhooks, until you receive a SubscriptionContractCalculationSuccess or SubscriptionContractCalculationFailure.
  3. Commit: call subscriptionContractCalculationCommit to persist the calculated snapshot.

Shopify calculates pricing, taxes, discounts, and Shopify Functions server-side and returns an immutable preview — including line, delivery, tax, duty, and discount totals — before you persist anything. Because the state is client-provided, any field you omit on update is preserved, so you only send what changed. For full details, see the migration guide.

Running through C1 also unlocks capabilities that were impossible with the drafts API: bundle products in contracts, cart transforms and delivery customization Functions, and pricing and tax that align with what the subscriber sees on recurring orders.

What to do

Action is required to adopt the new capabilities. The SubscriptionDraft object will be deprecated once the new API reaches general availability on 2026-10; it will remain available but won't support the new capabilities. Don't build production integrations until 2026-10 is stable.

We've written a full migration guide to support your move to the new API.

Related docs

Was this page helpful?