Developer / Subscriptions API

SubscriptionContractCalculation API
Subscription contract edits calculated with the same engine as checkout

Contract edits are now calculated by Shopify's checkout engine. Shopify Functions apply, results match what subscribers see at billing, and you can preview totals, delivery options, and warnings before saving. Migrating from the SubscriptionDraft API is recommended.

On this page
  1. What's changing (in 30 seconds)
  2. How it works: the flow from contract edit to calculation
  3. 3 new things you can do
  4. SubscriptionDraft API vs SubscriptionContractCalculation API
  5. Who it's for and where migration stands
  6. How to migrate (3 steps)
  7. 5 key points for developers
  8. 3 business use cases
  9. One-line summary for proposals

1What's changing

A new API for managing subscription contracts, SubscriptionContractCalculation API is now available.
Contract edits are calculated through Shopify's checkout engine , so the same calculation logic as regular checkout now applies to contract edits.

Before: SubscriptionDraft API

Still supported, but it doesn't get the newly announced features (Functions support, consistency with billing, calculated previews).

New: SubscriptionContractCalculation API

Calculates contract edits with the checkout engine. Shopify Functions apply, and you can preview the full calculated result before saving.

2How it works: the flow from contract edit to calculation

Contract edit The app/developer submits the changes STEP 1 Shopify checkout engine Shopify Functions:cart transform Shopify Functions:delivery customization Same calculation as at billing STEP 2: Calculate Preview of the calculated contract Totals Delivery options Warnings STEP 3: Review before saving Save changes STEP 4
The key point: "before saving (persisting)," you can review the calculated results. Before committing changes, you can retrieve the full calculated contract, including totals, delivery options, and warnings.
This article doesn't name specific mutations or fields. See the migration guide and API documentation.

3Three new capabilities

fx Functions

Shopify Functions apply

Shopify Functions such as cart transform and delivery customization are now supported when contracts are calculated.

= Consistency

Matches what's billed

Contract edits match what subscribers see at billing, so calculations no longer diverge between editing and billing.

Preview

Full preview before saving

Retrieve the complete calculated contract, including totals, delivery options, and warnings, before saving changes.

4SubscriptionDraft API vs SubscriptionContractCalculation API

ItemSubscriptionDraft API (existing)SubscriptionContractCalculation API (new)
Availability Still available Remains available Now available Available
Calculation engine Not stated Checkout engine used for calculations
Shopify Functions New features not supported Supported cart transform, delivery customization, etc.
Matches billing New features not supported Supported Matches what subscribers see at billing
Preview before saving New features not supported Supported Totals, delivery options, warnings
Deprecation date Not stated —

5Audience and migration context

Developers using the SubscriptionDraft API

The announcement explicitly says they should migrate to the SubscriptionContractCalculation API.

Available resources

A migration guide, updated subscription build guides, and API documentation are provided.

The target API version, required access scopes, eligible plans, and the SubscriptionDraft API deprecation timeline arenot statedin this article. Check the migration guide and API documentation.

6How to migrate (3 steps)

1

Read the migration guide

Review the official migration guide and the updated build guides and API docs.

2

Replace Draft usage

Switch any logic that edits contracts through the SubscriptionDraft API to the new API.

3

Validate with previews

Before saving, check totals, delivery options, and warnings to confirm the calculation behaves as intended.

The SubscriptionDraft API remains available, so existing implementations won't break right away. However, you'll need to migrate to use new features.

75 key points for developers

1. Calculation logic is shared with checkout

Contract edits run through the checkout engine, so they use the same calculation system as regular purchases. There's less need to replicate subscription-specific calculations yourself.

fx

2. Existing Functions also apply to contract edits

Cart transform, delivery customization, and others are explicitly listed as supported. Because the wording is "including," check the API documentation for which other Function types are covered.

3. Calculating and saving are separate

You can retrieve the calculated contract (totals, delivery options, warnings) before saving. This lets you design UI and logic that handle warnings before committing changes.

=

4. No more mismatch between editing and billing

Edits now match what subscribers see at billing time. This reduces the risk of support inquiries caused by differences between the amount shown during editing and the actual charge.

5. The SubscriptionDraft API stays, but won't grow

The Draft API remains available but won't support new features. It makes sense to build new implementations on the SubscriptionContractCalculation API from the start and plan migrations for existing ones. The deprecation timeline isnot stated.

83 practical use cases

SET
USE CASE 1

Apply the same bundle logic when editing subscriptions for bundles and sets

Challenge
Bundles are built with cart transform for regular purchases, but the same logic doesn't apply when editing subscription contracts, so contents and pricing diverge from regular purchases.
Approach
Migrate contract editing to the SubscriptionContractCalculation API so your existing cart transform also applies to contract calculations.
Impact
Unify product composition logic across regular purchases and subscriptions, reducing duplicate implementations and differences in operational rules.
Technical note
Cart transform is explicitly listed as supported in contract calculations. Verify actual behavior using the migration guide and a test environment.
Delivery options
USE CASE 2

Add a pre-confirmation preview to delivery changes in the customer account page

Problem
When subscribers change their shipping address or delivery method, they can't see the updated total or available delivery options before confirming, so the next billing amount catches them by surprise.
Approach
Calculate the changes with the new API, show the totals, delivery options, and warnings on screen, then have the subscriber confirm.
Impact
Show amounts upfront that match what will actually be billed, reducing "this isn't what I expected to pay" inquiries and churn risk.
Tech notes
Delivery customizations are also supported in contract calculations. Plan how warnings will be shown in the UI as part of the design.
USE CASE 3

Preventing errors when support agents edit contracts

Problem
When CS agents edit contracts while handling inquiries, they sometimes notice pricing errors only after saving, which leads to re-edits and refunds.
Approach
Rebuild the internal contract editing tool on the new API, with a flow that always requires reviewing the calculated contract (totals, delivery, warnings) before saving.
Impact
Pre-save checks reduce editing mistakes and cut down on rework and refunds.
Tech notes
Existing tools built on the SubscriptionDraft API keep working as-is, but you'll need to migrate to use the preview feature.

9One-line summary for proposals

"A new API that calculates subscription contract edits using Shopify's checkout engine.
Functions are applied, so you can preview the same result you'll get at billing time—before saving.
If you're using the SubscriptionDraft API, plan a migration to take advantage of the new features."