> For the complete documentation index, see [llms.txt](https://docs.roadmap.so/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadmap.so/subscriptions/storefront-and-accounts/loyalty-points-subscriptions.md). # Loyalty points × subscriptions How loyalty points work on subscription contracts — earning, redeeming on upcoming orders, and the surfaces where it shows up in the admin and storefront. Loyalty points behave on subscriptions the way they behave on regular orders: customers earn points when they're charged, and they can spend points on a discount against an upcoming order. The integration runs in three places — the contract page in the admin, the per-cycle ••• menu (also admin), and the customer's storefront subscription card. This article covers how each surface works, what merchants can do that customers can't, and the validation rules that explain why a redemption is sometimes disabled. #### How earning works Every successful subscription billing earns the customer points the same way a one-time order does — based on the points-per-dollar ratio configured in your loyalty rules. A few subscription-specific specifics: * Order Now charges earn points the same as a scheduled cycle. * Failed billing attempts earn no points — points only credit on successful charges. * Redemption discounts are applied before points are calculated, so a redeemed cycle earns points on the discounted subtotal, not the pre-discount one. * The customer's points balance lives on their Shopify customer account, not on any single subscription contract. Canceling a subscription doesn't lose them their points. For why a customer's specific order didn't earn the points they expected, see Why didn't a customer earn loyalty points? Check their Timeline. #### Where loyalty shows up on a subscription contract Open any contract from Subscriptions → Manage Subscriptions. In the right-hand rail you'll see a Loyalty Points card showing: * The customer's current points balance * A View loyalty account link that opens the customer's full loyalty profile (history, tier, redemptions across all orders, not just subscriptions) The Loyalty Points card is informational. To actually redeem points against an upcoming subscription order, you use the per-cycle ••• menu (next section) or the customer does it from their account. #### Redeeming points (the customer's path) From the storefront My Subscriptions page, the customer: 1. Opens Manage Subscription ▾ on the contract they want to apply points to. 2. Chooses Redeem loyalty points. 3. The dialog shows their current balance and every configured redemption option (e.g., "100 points = $10 off", "500 points = 20% off"). 4. Each option is enabled or disabled based on the validation rules below. The customer picks one and confirms. 5. The discount is applied to their next billing cycle, and the points are deducted immediately from their balance. #### Redeeming points (the admin's path) From the contract page, find the Upcoming order you want to apply points to in the Orders list, click its ••• menu, and choose Redeem Loyalty Points. You see the same dialog the customer sees — same options, same disabled-state logic — and confirm on the customer's behalf. Use this when: * The customer asks you over chat or email to redeem on their behalf. * You're recovering a contract and want to apply a goodwill discount using points the customer already has. * You want to apply points to a specific upcoming order rather than the next one (the customer's storefront flow always applies to the next cycle; the admin per-cycle menu lets you target any future cycle). #### What makes a redemption option enabled vs disabled When the dialog opens, every option is evaluated independently. An option is disabled if any of these are true: | Reason | What's checked | | ----------------------------- | -------------------------------------------------------------------------------------------------- | | Insufficient points | The customer's balance is less than the option's points cost | | Below minimum order | The targeted cycle's subtotal (before discounts) is below the option's minimum-order-value setting | | Would make the total negative | The discount value is larger than the targeted cycle's current total | Disabled options are still shown so the customer (and you) can see what's available and what they'd need to qualify. #### Validation that runs at submit time The dialog's enabled/disabled states reflect the situation when the dialog opened. When the customer or you press Redeem, Roadmap re-validates: * Subscription status — must be Active. Paused, Failed, or Cancelled contracts can't have points redeemed against them. * Cycle eligibility — the targeted cycle must be in the future (`billingAttemptExpectedDate > now`), unbilled, and not skipped. * Points balance — re-checked at submit time, not when the dialog opened. If the customer's balance changed in between, redemption can be blocked. * Redemption method active — the redemption option must still be configured and enabled in your loyalty settings. * Per-order limit — if your loyalty configuration limits redemptions to one per order, a cycle that already has a loyalty redemption applied will block additional redemption. If validation fails at submit time, the customer or you see an error explaining which check failed. #### What the customer sees on a redeemed cycle * On their account page, the upcoming order shows the discount applied with a "Loyalty discount: $X off" line. * When the cycle bills, the order in Shopify includes the discount and the points deduction is finalized. * The Activity Timeline on the contract records the redemption with the actor (customer or merchant), the points spent, and the cycle it applied to. #### Common scenarios **"The customer says the redeem option is disabled but they have plenty of points"** Most often this is the minimum order value check. The redemption option requires the cycle's subtotal to be at or above a configured threshold; if the customer's upcoming order is below that, the option is disabled even with sufficient points. Adjust the contract (add a product, swap to a higher-priced variant) or use a different redemption tier. **"Customer redeemed but the discount didn't apply"** Confirm the cycle hasn't already billed. Redemptions only apply to future, unbilled cycles. If the customer redeemed on a cycle that was already in flight, the validation should have blocked it — but if you're seeing a discrepancy, check the Activity Timeline for the redemption event and the order in Shopify to compare. **"Customer canceled their subscription — what happened to their points?"** Nothing. Points are stored on the customer's Shopify account, not on the contract. They keep their balance and can spend it on any future order, subscription or otherwise. #### Related guides * The Subscription Activity Timeline * Editing a customer's subscription * What customers can do from their account page * Why didn't a customer earn loyalty points? Check their Timeline --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.roadmap.so/subscriptions/storefront-and-accounts/loyalty-points-subscriptions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.