The Shopify Subscription Contract API, explained for developers

Why this API exists (and what it replaced)

Shopify's original subscription support was a thin layer of webhooks and metafields layered on Stripe Subscriptions — apps maintained the canonical schedule in their own database, billed customers through a separate Stripe account, and synced orders back into Shopify after the fact. That model produced reliability problems (orders missing from Shopify's reporting, inventory not decrementing, refund flows that didn't agree between systems) and platform problems (customers being billed by an app, not by Shopify, which violated the merchant-of-record assumption Shopify Payments depended on).

In 2021 Shopify launched the Subscription Contract API: a redesign where Shopify itself is the merchant of record for every subscription charge, contracts are first-class records inside Shopify's database, the card is vaulted by Shopify Payments (not by the app), and billing is triggered through an explicit SubscriptionBillingAttempt mutation. The legacy Subscriptions API was deprecated and is no longer accepted for new apps — every subscription app on the App Store today builds on the Contract API. If you find tutorials or third-party blog posts referencing 'Shopify Subscriptions API' without 'Contract,' check the date: pre-2021 content is describing the deprecated surface and almost none of it is accurate anymore.

The core resources you'll model against

There are six resources every subscription app touches. Internalising what each one represents — and what it doesn't — saves a lot of confusion later.

• SellingPlanGroup — a collection of selling plans attached to one or more products. 'Subscribe & Save monthly' is typically a group containing a single monthly plan, but groups can hold multiple plans (e.g. weekly + biweekly + monthly under one 'Coffee subscription' group).
• SellingPlan — a single buyable subscription option: an interval, a discount, a delivery rule. Customers pick a SellingPlan when they subscribe; the contract records which plan was chosen.
• SubscriptionContract — the live agreement between merchant and customer. Holds status, customer reference, payment method, billing policy, delivery policy, pricing policy, lines, and the next billing date.
• SubscriptionLine — one product line on a contract. A contract typically has 1-5 lines (the products in the recurring order). Each line has its own price, quantity, variant, and reference back to the originating selling plan.
• SubscriptionDraft — a mutable, in-progress copy of a contract. You create a draft from a live contract, mutate it freely (add lines, change address, swap variants), then commit it back to replace the live contract atomically. This is the only safe way to make multi-field edits.
• SubscriptionBillingAttempt — the record of one attempt to charge a contract. Has a contract reference, an idempotency key, a status (ready / failed / completed), an error code on failure, and an order reference on success.

Selling plans are configured by the merchant (or by your app on their behalf) ahead of time and are reused across products. Contracts are created at customer signup. Drafts are short-lived. Billing attempts accumulate as a contract ages — a 2-year-old monthly contract has 24+ billing attempts in its history, which is useful audit data when investigating a dispute.

The shape of a SubscriptionContract

Most of your reads against the API are some flavour of 'load this contract with the fields I need.' The contract object is large but cleanly structured. Here's the canonical query shape your app will reuse constantly:

query GetContract($id: ID!) {
  subscriptionContract(id: $id) {
    id
    status
    nextBillingDate
    currencyCode
    customer { id email }
    customerPaymentMethod { id }
    billingPolicy { interval intervalCount }
    deliveryPolicy { interval intervalCount }
    deliveryPrice { amount currencyCode }
    deliveryMethod { ... on SubscriptionDeliveryMethodShipping { address { address1 city zip countryCode } } }
    lines(first: 50) {
      edges { node { id title quantity currentPrice { amount currencyCode } variantId sellingPlanId } }
    }
  }
}

Status transitions through ACTIVE → PAUSED → CANCELLED → EXPIRED, with FAILED as a holding state when billing attempts are failing. Billing policy and delivery policy are distinct: a 'pay every 3 months, ship every month' subscription is perfectly valid (used for prepaid quarterly plans). Lines are the products — each one carries its own selling plan reference, which matters because a contract can theoretically span multiple selling plans if your widget supports mixed-cart subscriptions.

Two important things missing from the contract: the credit card number (only the payment method ID is exposed), and the total amount of the next charge. Total is calculated at billing-attempt time from the lines + tax + shipping, so it's never stored on the contract. If you need to display 'your next charge will be $X' in your portal, you have to recompute it the same way Shopify will — sum the line prices, apply selling-plan pricing policy, add delivery price, apply tax estimate. Most apps approximate and accept a few cents of drift between portal display and final charge.

Selling plans and their three policies

A SellingPlan packages three policies: billingPolicy (when to charge), deliveryPolicy (when to ship), and pricingPolicy (what discount, if any, to apply). Each is independent. The common case — bill and deliver on the same interval, 10% off — looks like a single object but is technically three policies pointing at the same cadence with a fixed-percentage pricing rule.

Where it gets interesting is prepaid and multi-shipment plans. Prepaid: billingPolicy interval = 3 months, deliveryPolicy interval = 1 month — customer pays for 3 months upfront, gets 3 monthly shipments, then is billed again. Multi-shipment: same pattern, useful for box subscriptions where one charge funds multiple deliveries. Shopify supports both via the same selling plan shape — your app just configures the policies independently.

Pricing policy supports two modes: FIXED_AMOUNT (subtract a fixed dollar amount per cycle) and PERCENTAGE (subtract a percentage). It also supports adjustmentValue overrides per cycle, which is how 'first order 20% off, subsequent orders 10% off' is implemented — a fixed schedule of pricing policies keyed to cycle index. This is more flexible than most subscription tools and worth knowing if you're modelling promotional first-month deals. Deep dive on selling plans here.

SubscriptionDraft: the only safe way to mutate a contract

The most common mistake new integrators make is trying to update a live contract's lines, address, and pricing in three separate mutations. This race-conditions horribly: a cron tick can fire a billing attempt between mutation 1 and mutation 2, capturing the contract in a half-edited state. The fix is the draft pattern, which Shopify designed specifically to prevent this.

A draft is created from a live contract via subscriptionContractUpdate (which somewhat confusingly returns a draft, not a finished update). You then mutate the draft as many times as you want using draft-scoped mutations (subscriptionDraftLineUpdate, subscriptionDraftLineAdd, subscriptionDraftCommit, etc.). When the customer-portal save button is clicked, you call subscriptionDraftCommit, and Shopify atomically replaces the live contract with the draft's state. No half-edited contracts. No race with the billing cron.

Some operations bypass drafts because they're inherently atomic — pausing or cancelling a contract is a single status flip and has its own dedicated mutations (subscriptionContractPause, subscriptionContractCancel). Single-field updates like 'set next billing date' have a dedicated mutation too (subscriptionContractSetNextBillingDate). The draft pattern is specifically for multi-field edits and line-level changes.

SubscriptionBillingAttempt: how renewals actually fire

Renewals happen because your app fires a SubscriptionBillingAttemptCreate mutation against a contract. Shopify does not have a built-in cron that bills contracts — scheduling is the app's responsibility. Most apps run a worker every 15 minutes that queries for contracts where nextBillingDate is in the past and ACTIVE, then fires one billing attempt per contract.

mutation BillContract($contractId: ID!, $idempotencyKey: String!) {
  subscriptionBillingAttemptCreate(
    subscriptionContractId: $contractId,
    subscriptionBillingAttemptInput: {
      idempotencyKey: $idempotencyKey,
      originTime: null
    }
  ) {
    subscriptionBillingAttempt {
      id
      ready
      errorCode
      errorMessage
      nextActionUrl
      order { id name }
    }
    userErrors { field message }
  }
}

The idempotencyKey is required. Make it deterministic — a hash of contract ID + scheduled billing date is the conventional choice. If you submit the same key twice, Shopify returns the same billing attempt rather than creating a new one, which is your protection against accidental double-charges when your worker crashes mid-flight and retries.

The response field ready: false indicates Shopify accepted the attempt but hasn't completed it yet — billing attempts are async. The subscription_billing_attempts/success or /failure webhook is your authoritative signal that the attempt resolved. nextActionUrl appears for SCA challenges that need customer interaction. errorCode appears on synchronous validation failures (e.g., trying to bill a CANCELLED contract).

Webhooks: keeping your app in sync

Webhooks are how your app finds out about lifecycle events without polling. The set worth subscribing to is small. Subscribe via the webhookSubscriptionCreate mutation, ideally during app installation, and re-subscribe after any scope change.

• SUBSCRIPTION_CONTRACTS_CREATE — a new contract was created (first subscription checkout, or via API import during migration)
• SUBSCRIPTION_CONTRACTS_UPDATE — any field on a contract changed (address, lines, status, next billing date, payment method)
• SUBSCRIPTION_BILLING_ATTEMPTS_SUCCESS — a billing attempt resolved successfully and an order was created
• SUBSCRIPTION_BILLING_ATTEMPTS_FAILURE — a billing attempt failed; payload includes errorCode for branching dunning logic
• ORDERS_CREATE — the renewal order itself, useful for fulfillment-side handlers and reporting integrations
• CUSTOMERS_UPDATE — customer record changed, useful if you maintain a denormalised customer view

Two operational notes. First, webhooks can arrive out of order — design handlers as idempotent upserts keyed by the Shopify ID, never assume create-before-update. Second, Shopify retries failed webhook deliveries for up to 48 hours with exponential backoff; if your endpoint returns a 5xx, you'll see the event again, possibly several times. Return 2xx within 5 seconds (push real work to a background queue) or you'll be replaying events all afternoon.

App Bridge vs raw GraphQL: when to use which

Most subscription apps embed an admin UI inside Shopify using App Bridge — Shopify's iframe-aware UI framework. App Bridge gives you session-token authentication, host-aware navigation, Polaris web components for native-feeling UI, and direct access to the Admin GraphQL API from the embedded app. For merchant-facing screens, this is the right default — you get authentication, theming, and embedding for free.

Raw GraphQL (server-to-server, with an offline access token from OAuth) is the right choice for: cron-triggered billing, webhook processing, batch operations, anything that doesn't have a logged-in merchant in front of it. The OAuth offline token, scoped narrowly to what your app needs, is what your cron worker uses to authenticate. You'll fire SubscriptionBillingAttemptCreate from a server worker using this token, not from the merchant's browser via App Bridge.

A few hybrid patterns are worth mentioning. The customer portal (where subscribers manage their own contracts) typically lives on a public storefront-adjacent domain — neither admin App Bridge nor server cron, but a third surface that authenticates via Shopify Customer Account API tokens. The Subscription Contract API can be called with these customer tokens via the storefront-adjacent endpoints, with permissions automatically scoped to the customer's own contracts. This is how SimpleSubscription's customer portal avoids exposing admin scopes to the subscriber-facing surface.

OAuth scopes and Protected Customer Data

Subscription apps need a specific bundle of scopes that's larger than most Shopify apps. Get this right at install time — adding scopes later forces a re-authorisation prompt that some merchants ignore for weeks.

• read_own_subscription_contracts, write_own_subscription_contracts — required for any contract operations
• read_customers, write_customers — required to associate contracts with customer records and update addresses
• read_orders, write_orders — required to read renewal orders and handle refunds/fulfillment
• read_products, write_products — required to read subscribable products and attach selling plans
• read_purchase_options, write_purchase_options — required to create and manage selling plan groups
• read_customer_payment_methods — required to read the payment method handle a contract bills against
• read_discounts, write_discounts — required if you support promotional discounts at signup

On top of OAuth scopes, Shopify applies Protected Customer Data rules to any app that reads PII. Subscription apps invariably do (customer email, name, address are all PCD). You'll go through Shopify's protected customer data review during App Store submission, which requires: a privacy policy, opt-in disclosure for what PCD you collect, documented retention periods, and a data-deletion flow (GDPR-style). Plan for 2-4 weeks for this review on first submission.

API gotchas that will trip you up

A non-exhaustive list of things that don't appear in the reference docs but will eat days of your time if you don't know about them upfront.

• Partial line updates are awkward — there's no 'update line X's quantity from 2 to 3' direct mutation, you go through the draft pattern, mutate the line, commit. This is fine but feels heavier than it should for a one-field change.
• Status transitions are gated — you can't reactivate a CANCELLED contract; you have to create a new one. PAUSED → ACTIVE is supported. Plan your UI around this constraint.
• Gift card eligibility for subscriptions is limited — gift cards can't pay for subscription renewals because they can't be vaulted. Your widget should disallow gift-card-only checkouts when a selling plan is in cart.
• Rate limits apply to the GraphQL Admin API: the bucket is 1000 cost-points per app per shop, refilling at 50 points/second. subscriptionBillingAttemptCreate costs more than a typical query — pace your billing batches accordingly. At very high volume, contact Shopify Partner Support about higher limits.
• Idempotency keys are scoped per contract — the same key on different contracts is fine. The key collision check is contract-local.
• Time zones on nextBillingDate are stored in UTC but displayed in merchant local time in the admin — your cron logic should always compare in UTC to avoid off-by-one-day bugs around DST transitions.

Testing patterns: dev stores, bogus gateway, and dry-run billing

Shopify provides a bogus payment gateway for development stores that simulates real payment behaviour without moving actual money. Card number 1 succeeds, 2 fails generically, 3 fails with insufficient funds — useful for testing dunning flows. Enable it under Settings → Payments → 'Manual payment methods' on a dev store, and treat it as your default for integration tests.

For end-to-end billing tests, the conventional pattern is: create a development store, install your app, create a real subscription contract via your widget, manually advance the contract's nextBillingDate using subscriptionContractSetNextBillingDate to one minute in the future, let your cron fire the billing attempt, and observe the webhooks. This exercises the full pipeline without waiting 30 days. Always clear bogus gateway charges by deleting the dev store at the end of a test session — they don't appear in any payout but accumulate in admin reporting.

For load testing the billing cron, generate hundreds of contracts in a dev store and advance them all to the same near-future date, then watch how your worker behaves. The most common bug at this layer is concurrent billing attempts on the same contract from two worker instances — a properly-keyed idempotency strategy makes this safe, but a sloppy one will double-charge. Test it before production.