Executive summary
- What: A new SubscriptionContractCalculation API runs subscription contract edits through Shopify's checkout engine, consolidating the multi-step SubscriptionDraft flow into four calculate operations plus a shared commit.
- Why: Pricing, tax and discount results now align with what the subscriber is actually billed, and cart transform and delivery customization Functions run during the calculation.
- Who: Merchants running subscriptions through anything built on SubscriptionDraft, and the developers maintaining it.
What changed
Contract edits previously went through SubscriptionDraft: create a draft, apply a series of mutations, commit. Calculation happened outside checkout, which is why an edited contract could price differently from what the billing cycle later produced. The new API consolidates those mutations into calculate operations plus a shared commit, and runs them through the same engine that prices a checkout. It is asynchronous, so a request is polled rather than answered immediately, and it returns a full calculated preview before anything persists: line totals, delivery, taxes, duties, discounts, delivery options and warnings. Cart transforms and delivery customizations are supported now, with other Shopify Functions following in later releases. It requires API version 2026-10 and the write_own_subscription_contracts scope, and it is in early access. SubscriptionDraft keeps working but will not gain these capabilities.
Why it matters
The long-standing complaint about subscription contract editing on Shopify is that the edit and the eventual charge do not always agree. A swap, a quantity change or an added line could produce one total in the edit flow and a different one when billing ran, because discounts, taxes and Function logic were applied in different places. Running edits through checkout closes that gap.
The preview is the more valuable half. A support agent or an automated flow can see exact totals, delivery options and warnings before committing, which turns a billing dispute into a conversation that happens before the charge rather than after it. For merchants where subscriptions are a core revenue line, that is a measurable reduction in contact volume. The cost is real engineering work: asynchronous calculation with polling is a different control flow from synchronous draft mutations, and error and warning handling has to be rebuilt rather than ported.
Role-specific impact
- Marketers: Subscription offers that rely on Functions, such as bundled cart transforms or delivery customizations, now behave consistently when a contract is edited, so promotional mechanics survive subscriber changes.
- Developers: Plan a migration from SubscriptionDraft. Move to 2026-10, add write_own_subscription_contracts, implement polling, and map the returned cost breakdown and warnings into your own surfaces. Expect early access behaviour to shift.
- Store admins: Fewer discrepancies between what a contract edit shows and what the subscriber is charged, plus a preview to check before committing a change on a customer's behalf.
Use-case example
Real-world scenario
A supplements brand on Shopify Plus carries about 40,000 active subscriptions and processes roughly 900 contract edits a month through its support team: swaps, quantity changes and address updates. Around 3 percent of those edits generated a follow-up ticket because the next charge did not match what the agent quoted, almost all of them on contracts where a bundle cart transform or a delivery customization applied. Calculating the edit through checkout and showing the agent the full breakdown before commit addresses the cause rather than the symptom, and takes that contact driver close to zero.
Implementation checklist
- Confirm whether your subscription app or custom integration uses SubscriptionDraft today.
- Request early access and read the migration guide before changing any code.
- Move the integration to Admin API version 2026-10 and add the write_own_subscription_contracts scope.
- Implement asynchronous polling for calculation results, with sensible timeout and retry behaviour.
- Surface the calculated breakdown and warnings to whoever commits the edit, whether that is an agent or an automated flow.
- Validate against contracts that exercise cart transforms and delivery customizations, not just simple single-line contracts.
- Keep the SubscriptionDraft path in place until the new flow is proven in production.
FAQ
Q: Is SubscriptionDraft being deprecated?
A: Shopify says it remains available. It will not receive the new capabilities, so treat it as frozen rather than removed and plan migration on your own schedule.
Q: Do we have to adopt this to keep subscriptions working?
A: No. Existing contracts and flows continue to operate. Adopt it when pricing consistency with checkout, or Function support during edits, is worth the migration effort.
Resources
Migrate to the SubscriptionContractCalculation API
Need guidance? Talk to Makro.