Shopify selling plans, explained — billing, delivery, pricing policies

What a selling plan actually is

A selling plan is a Shopify object that tells the storefront, cart, and checkout: "this product can be purchased on a recurring schedule, here's how often, here's the price, and here's when the customer is charged." It is not a separate product. It is metadata attached to one or more existing products (or variants) describing how the recurring version of the purchase behaves. The product, its inventory, and its variants stay exactly as they were — a selling plan just says "and you can also buy this one every 4 weeks at 10% off."

Three things distinguish a selling plan from a legacy subscription system or a one-time product. First, it lives inside Shopify's Subscription Contract API — a renewal creates a real Shopify order with real tax, real shipping, real fulfillment records. Second, the customer's payment method is vaulted at first checkout through Shopify Payments (or another supported gateway with stored-card support), so renewals charge without the customer touching anything. Third, all three policies — billing, delivery, pricing — are defined on the selling plan itself, not on the product, which means the same product can be offered on multiple schedules without duplicating SKUs.

• Selling plan: a single recurring offer (e.g. "every 4 weeks, 10% off")
• Selling plan group: a collection of related plans attached to one or more products (e.g. weekly + monthly + quarterly cadences for the same coffee bag)
• Subscription contract: the record of one customer's active subscription created at checkout from a selling plan
• Subscription billing attempt: the renewal-day API call that creates a new order from the contract

Billing policy — when and how often the card gets charged

The billing policy answers a single question: when does Shopify charge the customer's card? It has two main shapes: recurring (charged every N days/weeks/months indefinitely until cancelled) and fixed (a prepaid plan that charges once and delivers N times, like "pay today, get 3 months of coffee"). Most stores start with recurring and add fixed later for gift subscriptions or prepay-and-save offers.

For recurring plans, the billing interval doesn't have to match the delivery interval. A prepaid box subscription might bill quarterly (one charge, $90) but deliver monthly (one box per month). That's expressed as billingPolicy.interval = MONTH, intervalCount = 3, with a delivery policy of MONTH/1. Shopify's API lets you decouple billing from delivery, which is what makes prepaid and bulk-discount offers possible without writing custom code.

Two billing-policy concepts catch out new merchants. The first is the anchor date — does "every 4 weeks" mean exactly 4 weeks from each customer's signup date, or every 4 weeks aligned to the 1st of the month? The default is signup-relative (each subscriber renews on their own anniversary). Calendar-anchored renewals are useful when you want fulfillment concentration (e.g. weekly produce box all ships every Tuesday), but they create traffic spikes and need a 3PL that can absorb them. The second is the maximum cycle count — leave it null and the plan continues until the customer cancels; set it to 3 and the contract auto-completes after 3 renewals, which is how you build a fixed-term gift subscription.

Delivery policy — when fulfillment actually triggers

The delivery policy says how often the product physically ships. For most subscriptions it matches the billing interval — charge monthly, ship monthly. Where it diverges is on prepaid plans: charge once, ship monthly for 3 months. The delivery policy carries its own interval (DAY, WEEK, MONTH, YEAR), interval count, and an anchor that defines when within that interval the order is generated for fulfillment.

The fulfillment trigger isn't automatic — it happens when the renewal creates the next Shopify order. The order then enters your normal fulfillment workflow (3PL, ShipStation, manual). This matters because if your subscription app's cron job fails to run on a renewal day, no order is created and no fulfillment trigger fires. Reliable cron infrastructure (cron-job.org pinging the app's renewal endpoint, or Shopify's own scheduling) is the difference between subscribers getting their orders and getting silent gaps.

Anchor dates inside the delivery policy are also where prepaid plans get their behaviour. A 3-month prepaid coffee subscription with delivery anchored to the 1st of each month means the customer's card was charged on day 0, but the second and third orders are auto-generated on the 1st of the following two months. The customer experiences three regular shipments; the merchant only sees one billing event.

Pricing policy — discounts, first-order incentives, and price overrides

The pricing policy on a selling plan is where most of the merchant-facing logic lives. You define the discount type (percentage, fixed amount, or fixed price), the value, and whether it applies to every recurring order or just the first. This is how you express "10% off, every order" vs "20% off first order, 10% off thereafter" — the latter is two pricing adjustments attached to the same plan, one with appliesOnFirstOrder = true and one with appliesOnEachOrder = true.

The output of the pricing policy is a value called perDeliveryPrice — the actual amount the customer pays per shipment after all discounts are applied. This is the authoritative price for that subscription line, and it is what Shopify's cart and checkout actually charge. The most common bug in subscription widgets is JavaScript that recalculates a discounted price independently (productPrice * 0.9) instead of reading perDeliveryPrice from the selling plan allocation that Shopify already computed. Always read the displayed price from the allocation, never from a JS-side calculation, or your widget price will drift out of sync with what the cart actually charges.

Pricing policies also support fixed price overrides — say "this plan sells for exactly $24, regardless of the underlying product price." Useful when the product's regular price changes seasonally but you want the subscription price stable, or when you're running a promo and need a one-off subscription tier at a specific price point. Fixed-price overrides ignore the product's compareAtPrice, so make sure the subscribers' perceived discount still tracks reality.

• PERCENTAGE: e.g. 10% off — recalculates if the underlying product price changes
• FIXED_AMOUNT: e.g. $5 off — stable absolute discount regardless of product price changes
• PRICE: e.g. "this plan sells for $24" — fixed price overrides any product price changes
• appliesOnFirstOrder: discount applies once, on the initial purchase
• appliesOnEachOrder: discount applies on every renewal

Selling plan groups: attaching plans to products

Selling plans don't attach to products directly. They live inside a selling plan group, and the group is what gets attached to one or more products or variants. A group is the unit a customer interacts with on the product page — the dropdown of available cadences is one group, and each option in that dropdown is one selling plan inside it.

This is why your customer portal, dunning emails, and analytics dashboards group subscriptions by plan rather than product: the plan is the recurring offer, and one product can belong to multiple groups (e.g. a coffee bag in both "monthly coffee subscription" and "prepaid 3-month coffee gift"). When you query the API for a contract's subscribed line items, you get the selling plan ID alongside the variant ID — that's the join key for everything analytics-related.

Attachment can be per-product or per-variant. Per-product is simpler but less flexible: every variant of the product is subscribable on the same terms. Per-variant lets you, for example, offer the 12oz bag on monthly subscription but require the 5lb bag to be purchased one-time only. Most stores start per-product and only move to per-variant when they have a clear SKU-level reason.

Cart, checkout, and order behaviour with selling plans

When a customer adds a subscribable product to their cart with a selling plan attached, Shopify treats it as a different line item than the one-time version of the same product. The cart shows the line with the plan label ("Coffee — Monthly subscription, 10% off"), the perDeliveryPrice, and the next charge date. At checkout, Shopify Payments (or a supported gateway) vaults the customer's card and creates a subscription contract alongside the regular order.

The first order is a normal Shopify order — it shows up in the Orders admin like any other purchase, with full tax and shipping calculation, fulfillment workflow, and customer notification email. The difference is the order has a subscription contract attached, and on the contract's next billing date, Shopify's API will trigger a new billing attempt that creates a follow-up order using the vaulted payment method.

Tax and shipping are recalculated at every renewal — they're not frozen at signup. If a customer's shipping address changes through the portal, the next renewal recalculates shipping rates and tax based on the new address. This means your selling plan doesn't need to encode shipping cost; Shopify's shipping zones and rates apply at renewal time exactly as they would on a fresh one-time order. The same is true for VAT and state sales tax — Shopify Tax recalculates per renewal using the renewal-date address.

Mixed carts: subscription + one-time in the same checkout

A single Shopify checkout can contain both subscription line items and one-time line items. The customer pays once for everything at checkout; the subscription items create contracts and the one-time items behave normally. This is one of the under-appreciated benefits of Shopify's native selling plan system — legacy subscription apps used separate checkouts for subscriptions, which broke conversion and confused customers who couldn't combine a subscription bag of coffee with a one-time gift mug in the same order.

There are a couple of constraints. All subscription items in a mixed cart must share the same shipping address (Shopify can't split a contract across addresses). All subscription items must be available through a gateway that supports stored payment methods — adding a subscription item from a payment-method-incompatible gateway will block checkout. And shipping rates are calculated once for the combined cart at checkout, not per-line — if you ship subscriptions and one-times from different warehouses, your shipping configuration needs to account for it.

Edge cases: gift cards, B2B, multi-currency, discount stacking

Selling plans interact with the rest of Shopify in ways that aren't obvious from the docs. Here are the edge cases that bite merchants and the developers building on top of the platform.

• Gift cards: customers can apply a gift card to the first order of a subscription, but Shopify won't auto-apply remaining gift card balance to subsequent renewals — the renewal charges the vaulted card in full. If a customer expects their $50 gift card to carry across three $20 renewals, they'll be surprised; document this in your subscription FAQ.
• B2B price lists: Shopify B2B catalogs can have wholesale prices on the underlying product, but a percentage-off selling plan applies on top of the B2B price, not the retail price. A 10% subscription discount on a product that's also 30% off via wholesale catalog stacks to ~37% off. Use FIXED_AMOUNT or PRICE pricing policies if you don't want B2B and subscription discounts to compound.
• Multi-currency (Shopify Markets): selling plans price in the shop's default currency, and Markets converts at checkout using the current FX rate. If you offer a $24 subscription and a customer in EUR pays €22 today, in 4 weeks the FX rate may have shifted — Shopify converts at the renewal-day rate, so the customer might pay €21.40 or €22.60. This is usually fine, but it surprises customers in volatile currencies.
• Discount stacking with site-wide promotions: a 10% subscription discount applied through the selling plan, combined with a 20% Black Friday site-wide automatic discount, can stack to ~28% off (multiplicatively) and lock that price in for every renewal. Most subscription apps offer a "don't combine with other discounts" setting on the selling plan group — turn it on before any sale.
• Product deletion: deleting a product that's attached to an active subscription contract orphans the contract — Shopify will pause it on the next renewal attempt. Archive instead of delete if you have subscribers on that SKU, then migrate them to a replacement product through the app's swap feature.

Inspecting selling plans via the GraphQL Admin API

Every selling plan, group, and contract is queryable through Shopify's GraphQL Admin API. If you're a developer building a custom subscription experience, an analytics integration, or just want to audit what plans exist on a store, this is the entry point. The basic shape of a selling plan group query looks like this:

query SellingPlanGroups {
  sellingPlanGroups(first: 10) {
    edges { node {
      id
      name
      sellingPlans(first: 5) { edges { node {
        id
        name
        billingPolicy { ... on SellingPlanRecurringBillingPolicy { interval intervalCount } }
        deliveryPolicy { ... on SellingPlanRecurringDeliveryPolicy { interval intervalCount } }
        pricingPolicies { ... on SellingPlanFixedPricingPolicy { adjustmentType adjustmentValue { ... on MoneyV2 { amount currencyCode } } } }
      }}}
      products(first: 5) { edges { node { id title } } }
    }}
  }
}

Two endpoints matter most in practice. sellingPlanGroups lists every group on the shop with its attached plans and products — useful for an admin audit or a migration script. subscriptionContracts lists every active subscription on the shop with the customer, payment method, and next billing date — that's what your billing cron job iterates over each day to know who to charge. Both endpoints respect the read_own_subscription_contracts and read_purchase_options scopes; without those scopes your queries return empty arrays with no error, which is its own debugging trap.

When you need multiple selling plan groups

Most stores start with one selling plan group per product line — "monthly coffee subscription" containing weekly, biweekly, and monthly plans. That's enough for a long time. You'll know you need a second group when one of these patterns appears.

• Prepaid vs recurring on the same product: a coffee bag offered both as "monthly recurring, 10% off" and as "prepay 3 months, save 15%" — these are different billing behaviours and belong in separate groups so the product-page widget can present them as distinct choices
• Gift subscriptions: fixed-term plans (3 months, 6 months) sold as gifts behave differently from open-ended subscriptions and need their own group with maxCycles set
• B2B vs DTC pricing: a wholesale customer-list-restricted plan with B2B-only pricing alongside the standard retail plan; the storefront only shows the appropriate group based on customer tags
• Membership tiers: a Plus tier with deeper discounts gets its own group, with eligibility gated by customer tag or app logic

The cost of adding a second group is mainly UX: the product-page widget has to present multiple groups intelligibly. Most subscription apps handle this by showing tabs or radio buttons for groups, then dropdowns within each for plan selection. If you find yourself with four or more groups on a single product, take a hard look — that's usually a sign the choice architecture is overwhelming customers and adoption will suffer.

Pitfalls: pricing overrides during sales, anchor confusion, and silent failures

The pitfalls that wreck a launch usually come from misunderstanding how selling plans interact with the rest of Shopify, not from the API itself. Here are the recurring ones that show up in support tickets month after month.

Silent failures are the worst category. A misconfigured cron that doesn't run, a deprecated scope that returns empty arrays, a discount that stacks unexpectedly — none of these throw errors. They just produce wrong numbers in the analytics dashboard and confused customer emails. The defense is structured logging at every step of the renewal pipeline (billing attempt initiated, order created, fulfillment triggered, notification sent) so you can audit the trail when something looks off. Most subscription apps surface this in their admin UI; if yours doesn't, that's a signal worth taking seriously.