What is Subscription Contract?
A subscription contract is Shopify's core GraphQL object that represents the recurring billing agreement between a merchant and a customer. It is the authoritative billing source of truth inside Shopify for subscription status, billing policy, delivery policy, and billing attempts. Subscription apps may manage additional state, but the Shopify subscriptionContract object is the canonical record merchants should reconcile against when investigating billing failures or lifecycle mismatches.
What information lives on a Shopify subscription contract?
A subscription contract contains the recurring agreement details: customer identity, billing schedule, delivery schedule, line items, payment method linkage, and status values such as ACTIVE, PAUSED, or CANCELLED. It also acts as the parent record for the billing attempts created during renewals.
Because the contract sits inside Shopify's Admin GraphQL API, it is the cleanest place to audit the merchant-facing truth of a subscription. If your app layer says one thing and the Shopify contract says another, the mismatch must be investigated before you trust any operational reporting.
Why is the subscription contract important for monitoring?
Monitoring systems need one source of truth, and in Shopify that source is the subscription contract. Billing attempt error codes, current lifecycle status, and renewal history all attach back to this object, making it the best anchor point for reconciliation jobs.
Merchants who only look at their subscription app dashboard miss critical context when app state drifts from Shopify state. Reading the subscription contract directly lets you confirm whether Shopify believes a subscription is active, paused, cancelled, or failing at the billing-attempt layer.
Frequently asked questions
Is the Shopify subscription contract the same thing as a subscription app record?
No. Subscription apps such as Recharge, Bold, or Skio may store their own subscription objects, billing schedules, and status fields. The Shopify subscription contract is the native Shopify object underneath or alongside those app records. When the two disagree, you are looking at a cross-stack state mismatch.
Can a subscription contract be active while billing is still failing?
Yes. A subscription contract can remain ACTIVE even when recent billing attempts have error codes or a connected subscription app has already cancelled on its own side. That is why merchants must inspect both contract status and billing-attempt history instead of assuming ACTIVE means revenue is collecting normally.
Related guides
Detect subscription failures automatically
Free cross-stack scan. Find revenue leaks in 60 seconds.
Run Free Scan →