# Subscription milestones

{% hint style="info" %}
This feature is available for **Advanced** and **Ultimate** plans.
{% endhint %}

### Overview

**Subscription milestones** track **consecutive successful billing cycles** across a customer's subscription contracts and trigger rewards when they hit specific renewal targets.

#### When to use this

* You sell subscription products and want to **reduce churn**
* You want to reward long-term subscribers for their commitment
* You want to incentivize customers to keep their subscription active rather than canceling

### How to set up

When you open the Subscription milestone config page, you'll see a setup guide with 4 steps:

<figure><img src="/files/SSmkN5dtfLAG42DKDch5" alt=""><figcaption></figcaption></figure>

#### Step 1: Ensure Shopify Flow is connected

Go to **Settings → Integrations** and make sure **Shopify Flow** is connected to Joy.

#### Step 2: Import the Flow template (Required)

The subscription milestone needs a **Shopify Flow workflow** to track billing cycle data. Here's how to do it:

**Manual import**

1. Download the Flow template file: Joy Loyalty – Subscription Order Data Sync.flow below:

{% file src="/files/G6lx375nAAB0x89qUJEg" %}

2. In your Shopify admin, go to **Apps → Shopify Flow**
3. Click **Import** (top-right corner)

<figure><img src="/files/uIZWAlD4J1M1ZwILpTYz" alt=""><figcaption></figcaption></figure>

4. Select the downloaded `.flow` file

<figure><img src="/files/6jUO96gYyvnx5ivPMEGq" alt=""><figcaption></figcaption></figure>

5. Review the workflow and click **Turn on**

<figure><img src="/files/7kAOGnozKBHkT4OArr39" alt=""><figcaption></figcaption></figure>

> **Why is this needed?** Shopify doesn't send subscription renewal data to apps by default. This Flow template listens for subscription billing events and sends the data to Joy, so we can count billing cycles for your milestones.

#### Step 3: Set up your milestone rules

1. **Rule name:** Give your milestone a descriptive name (e.g., "6-Month Subscriber Reward")
2. **Start date / End date:** Set the active period (end date is optional)
3. **Milestone condition:** Set the number of **successful billing cycles** required
   * Example: Set to `6` to reward customers after their 6th consecutive renewal
4. **Rewards:** Choose one or more rewards (**Bonus points**, **Gift**, or **Discount**)

<figure><img src="/files/XDbT8gGZ7jwtLzcukJJ0" alt=""><figcaption></figcaption></figure>

#### Step 4: Activate the program

Click **Save** to apply your changes, then click **Turn on** to start tracking.

### How it works

* The milestone counts **consecutive successful billing cycles** for each subscription contract
* If a customer has multiple subscriptions, only **one** needs to reach the milestone to trigger the reward
* Each customer receives the reward **once per milestone** — not per subscription contract

### Important notes

* **Paused subscriptions** do not reset progress. When resumed, the cycle count continues from where it left off
* **Cancelled or expired subscriptions** will reset the cycle count for that contract
* **Upgrade/downgrade** of a subscription plan does not reset progress (as long as the subscription isn't cancelled)
* **Prepaid subscriptions** (one-time payment covering multiple cycles) are not supported and will not count toward this milestone

### FAQ

**Does each subscription contract count separately?** No. The milestone is per customer, not per contract. If a customer has 2 active subscriptions and both reach the milestone threshold, the reward is only given once — on the first contract that qualifies.

**What happens if a customer cancels and resubscribes?** The cycle count resets. They start from 0 on the new subscription contract.

**Do I need a specific subscription app?** No specific app is required. The milestone works via **Shopify Flow**, which tracks billing events from any subscription app integrated with Shopify.

**Is this available on all plans?** Subscription milestones are available on **Advanced** and **Ultimate** plans.


---

# Agent Instructions: 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:

```
GET https://help.joy.so/reward-programs/milestone/subscription-milestones.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.