Call `sellingPlanGroupCreate` with a `name`, `merchantCode`, array of `sellingPlans` (each with billing policy, delivery policy, and pricing policy), and associate the group with product/variant IDs.
When a buyer selects a selling plan at checkout, Shopify creates a subscription contract; your app receives the `subscription_contracts/create` webhook.
Use `subscriptionContractCreate` to create a contract programmatically (for migrations), providing customer ID, billing and delivery policies, and line items.
To modify an active contract (pause, cancel, change cadence), call `subscriptionContractUpdate` which opens a draft; commit changes with `subscriptionDraftCommit`.
Initiate billing attempts with `subscriptionBillingAttemptCreate`; poll or listen to `subscription_billing_attempts/success` and `subscription_billing_attempts/failure` webhooks to track outcomes.
Handle failed billing by checking `subscriptionBillingAttempt.errorCode` and implementing retry logic; after a configurable number of failures, cancel or pause the contract via `subscriptionContractUpdate`.
Known gotchas
`subscriptionContractCreate` creates a draft first — you must call `subscriptionDraftCommit` to materialize the actual contract; the draft ID and contract ID are different objects.
Selling plan billing and delivery policies must be compatible (e.g., delivery interval must be a multiple of the billing interval); mismatches return validation errors at group creation time.
Subscription contracts are owned by the app that created them; another app cannot modify a contract it does not own, which complicates migrations between subscription apps.
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