Shopify Subscription Contracts: How They Actually Work

A Shopify subscription contract is the database record behind every recurring order on the platform. It stores what ships, when it ships, how much the customer pays, and which card gets charged. Understanding how contracts work helps you pick the right subscription app (/shopify-subscription-app), troubleshoot billing issues, and avoid problems when switching platforms.

What is a subscription contract?

When a customer checks out with a product tied to a selling plan (like "deliver every 30 days, 10% off"), Shopify creates a subscription contract. That contract tracks the ongoing relationship: products, quantities, billing frequency, payment method, shipping address, and pricing. Your subscription app manages the contract through Shopify's Subscription Contracts API (https://shopify.dev/docs/apps/selling-strategies/subscriptions/contracts).

Selling plans vs contracts

This trips up a lot of merchants. A selling plan is a template. A contract is an instance of that template for a specific customer.

Selling plan: "Colombian Dark Roast, 12oz, every 30 days, 10% off." Contract: "Jane Doe subscribed to Colombian Dark Roast, 12oz, every 30 days, at $13.50, next billing April 15th, Visa ending 4242."

You create selling plans and attach them to products. Shopify creates contracts when customers buy. Your subscription app (SubZwallet, ReCharge, or others) manages both. Shopify documents selling plans here: Selling Plans API (https://shopify.dev/docs/apps/selling-strategies/subscriptions/selling-plans).

The billing cycle

Each contract has a billing policy that sets the charge date. On that date, your subscription app creates a billing attempt through the API. Shopify processes the payment against the stored card.

If the charge succeeds, Shopify creates an order. Simple. If it fails, the contract enters a failed state and your app's dunning logic kicks in: retry schedules, notification emails, and eventually a pause or cancellation if the payment is never resolved. SubZwallet retries failed charges 3 times over 7 days with different emails at each stage. Technical details: Billing Attempts API (https://shopify.dev/docs/apps/selling-strategies/subscriptions/contracts/billing-attempts).

Contract statuses explained

Active: billing on schedule. Normal state.
Paused: billing stopped temporarily. The customer keeps their spot and can resume anytime. SubZwallet uses pause-instead-of-cancel flows that save 15-25% of would-be cancellations.
Cancelled: billing stopped permanently. The contract remains in your records but generates no new orders.
Failed: the last billing attempt did not go through. Technically still active but needs payment resolution before the next cycle.
Expired: the contract hit its end date. Rarely used because most subscriptions are open-ended.

What customers can modify

Through the customer portal (provided by your subscription app), customers can make these changes without contacting support:

Swap products: switch variants or products entirely.
Change frequency: monthly to biweekly, or the reverse.
Skip a delivery: postpone the next charge without pausing.
Update payment method: replace an expired card.
Update shipping address: change delivery location.
Pause or cancel: stop billing temporarily or permanently.

Self-service portals reduce subscription support tickets by 40-60%. Shopify documents the payment side at: Customer payment methods API (https://shopify.dev/docs/apps/selling-strategies/subscriptions/customer-payment-methods).

How SubZwallet manages contracts

SubZwallet handles the full contract lifecycle: creating selling plans, tracking contracts, running billing attempts, managing dunning, and providing the customer portal. Where it differs from subscription-only apps like ReCharge is that SubZwallet layers loyalty on top of each contract. Subscribers earn points on every renewal, accumulate cashback in their wallet (/shopify-cashback-wallet), and progress through VIP tiers (/shopify-loyalty-program) based on subscription history.

That turns a billing record into a retention tool. A subscriber with 6 months of cashback in their wallet and Gold tier status is significantly harder to lose than one with just a recurring charge.

Common contract problems and fixes

Orphaned contracts: switching subscription apps can leave old contracts with no app managing them. Always migrate contracts when switching. SubZwallet handles ReCharge and Appstle transfers (/recharge-alternative).
Payment method expiry: cards expire and customers forget. Send pre-expiry reminders 14 and 7 days before. SubZwallet automates these.
Rigid frequency options: if you only offer monthly delivery, you lose customers who want biweekly or every 6 weeks. Create 3-4 frequency options upfront.
No pause option: when cancellation is the only way to stop deliveries, you lose subscribers permanently. Always offer pause.

Frequently Asked Questions

What is a Shopify subscription contract?: A subscription contract is Shopify's record of a recurring purchase agreement. It stores the products, billing frequency, payment method, and current status. Every active subscription has one contract managed through the Subscription Contracts API.
How do subscription contracts differ from selling plans?: A selling plan is the template (e.g., "every 30 days, 10% off"). A contract is the specific instance created when a customer checks out with that selling plan. Selling plans are the rules. Contracts are the individual subscriptions.
Can I migrate subscription contracts between apps?: Yes. SubZwallet includes a migration tool that transfers active contracts from ReCharge or Appstle, preserving payment methods and billing schedules. Most migrations complete in under an hour.