Ensure your app has the `write_own_subscription_contracts` (or `write_subscription_contracts` depending on app type) access scope — verify the exact scope name in current Shopify docs.
Call the `subscriptionContractCreate` mutation via the Admin GraphQL API, providing the customer ID, next billing date, status, selling plan ID, currency code, and billing and delivery policies.
On success, capture the returned `subscriptionContract` ID and the associated `subscriptionDraft` ID — Shopify uses a draft pattern where you must commit the draft to apply changes.
To update a contract, call `subscriptionContractUpdate` to open a new draft, make changes to the draft using `subscriptionDraftUpdate` and `subscriptionDraftLineItemAdd`/`Remove`/`Update` mutations, then commit via `subscriptionDraftCommit`.
Listen to the `subscription_contracts/update` webhook topic to track state changes and sync contract status to your system of record.
Query the contract with `subscriptionContract` query to retrieve billing attempts, line items, and delivery policy before initiating a billing attempt.
Known gotchas
Shopify subscription contracts use an immutable-draft pattern: you cannot edit a contract in-place. Every change requires opening a draft, mutating the draft, and committing it. Forgetting to commit leaves the contract unchanged and the draft open.
Subscription contracts are tightly coupled to selling plans — the selling plan defines the billing and delivery cadence. Creating a contract without a valid selling plan on the product variant will fail. Verify the variant has an active selling plan association before creating the contract.
The `nextBillingDate` must be a future datetime in ISO 8601 format. Passing a past date will fail validation. Account for timezone offsets — Shopify stores all datetimes in UTC.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp