Shopify Subscription Contracts Explained (2026 Guide)

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 (/), 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 (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 (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 on the schedule you set (0-10 retries, 1-14 days apart) with a branded email at each stage, then runs the final action you choose: skip, pause or cancel. Technical details: Billing Attempts API (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's cancel flow can offer a pause before the final cancel step.
• 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.

Every change a customer makes in the portal updates the same Shopify contract your team sees in the admin. In the SubzWallet portal, customers can also reschedule, order now (once a day), change quantities for the next order, add one-time add-ons, apply a discount code and leave an order note. Card updates go through Shopify, which emails the customer a secure link. Shopify documents the payment side at: Customer payment methods API (shopify.dev/docs/apps/selling-strategies/subscriptions/customer-payment-methods).

What can you see and edit on a subscription contract?

In SubzWallet, every contract has its own page under Subscription contracts. This is what a merchant sees and can change on one subscription contract:

• Overview: status, subscription ID, delivery frequency, next order date, customer details, shipping address, the card on file (brand and last digits, stored in Shopify) and the subscriber's lifetime value.
• Subscription products: the recurring lines billed every cycle, with quantity and price. You can change the quantity or price, swap the variant or product, and choose whether a discount carries over to the swapped product.
• Items on the upcoming order: change the next order only (quantity, a product left out of this order, one-time products or gifts added) without touching the recurring lines.
• Discounts: add a percentage or fixed-amount discount, for the upcoming order only or for every order, on the items you choose.
• Delivery schedule and upcoming billing: skip an order, reschedule the next order (optionally moving the orders after it), or edit the delivery frequency.
• Actions: pause, resume and cancel. When an order's payment has failed, Bill this cycle now charges it again right away instead of waiting for the next retry.
• Customer help: update the shipping address, send a payment-update email, or email the customer a sign-in link to manage the subscription themselves.
• Order history and activity timeline: past orders plus every change, skip, payment success or failure and retry, with dates.

If a renewal fails, the contract page shows a banner with the reason, the next retry date and what happens if the last retry fails. Out-of-stock renewals are flagged separately, with the product that is blocking the order.

Across contracts, the Subscription contracts list has tabs for upcoming orders, payment failed, out of stock, paused, cancelled and expired, with counts and search, and you can pause, activate or cancel in bulk. The subscription number is tagged on each order Shopify creates, so your team can match an order back to its contract.

How SubzWallet manages contracts

SubzWallet handles the full contract lifecycle on Shopify's native contracts: creating selling plans, tracking contracts, charging renewals, running dunning, and providing the customer portal. On top of each contract it adds retention tools: cancel flows with reasons and retention offers, and rewards. Subscribers earn points on every plan, can unlock milestone gifts on order #N (Launch and up), and on Growth and up can earn store credit in a cashback wallet after each billing and move through VIP tiers.

That gives subscribers a reason to keep the contract active beyond the recurring charge itself.

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 migrates subscriptions from ReCharge and Loop for free on every plan, and billing is switched on an agreed date so nobody is charged twice (ReCharge alternative).
• Payment method expiry: cards expire and customers forget. In SubzWallet, customers can update their card from the portal, and your team can send a payment-update email from the contract page. Failed charges go through your retry schedule.
• 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.

Further reading

• Shopify subscriptions overview (shopify.dev/docs/apps/selling-strategies/subscriptions)
• Contract management API (shopify.dev/docs/apps/selling-strategies/subscriptions/contracts/manage)
• Shopify Flow for subscription automation (help.shopify.com/en/manual/shopify-flow)
• SubzWallet getting started guide (help/getting started)
• SubzWallet manage subscriptions guide (help/manage subscriptions)

Want a subscription app that adds retention and rewards on top of contract management? Book a demo (demo) or install SubzWallet's Free plan to test with up to 50 active subscriptions.