> ## Documentation Index
> Fetch the complete documentation index at: https://subscriptions-docs.getappfox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription Rewards

> Offer rewards like free gifts, free shipping, and discounts after a specific number of billing cycles

## Overview

Subscription rewards let you incentivize customer loyalty by offering special benefits after customers have completed a specific number of billing cycles. This feature helps increase retention and encourages long-term subscriptions.

## Reward Types

When creating or editing a subscription plan, you can configure the following reward types:

### Percentage Off

Apply a percentage discount on qualifying orders.

* **Example**: 15% off from order 3 onwards
* **Use case**: Gradual discount tiers to reward loyal customers

### Amount Off

Apply a fixed amount discount from the order total.

* **Example**: \$5 off after 5 orders
* **Use case**: Simple dollar-value rewards

### Fixed Price

Set the order to bill at an exact price.

* **Example**: Order bills at \$20 after 10 cycles
* **Use case**: VIP pricing tiers for long-term subscribers

### Free Gift

Add a specific product variant at no charge to qualifying orders.

* **Example**: Free sample product after 3 orders
* **Use case**: Product upsells and customer appreciation gifts
* **Note**: Requires the Shopify product variant ID

### Free Shipping

Make shipping free on qualifying orders.

* **Example**: Free shipping after 5 orders
* **Use case**: Reduce friction for loyal customers

## Configuring Rewards

1. Navigate to **Subscription Plans** in your Shopify admin
2. Create a new plan or edit an existing one
3. Scroll to the **Reward** section
4. Toggle **Enable Reward** on
5. Select your **Reward Type**
6. Enter **After Cycle(s)** - the number of billing cycles before the reward applies
7. For percentage, amount, or fixed price rewards, enter the **value**
8. For free gift rewards, enter the **Product Variant ID**
9. Save your plan

## How Rewards Work

* Rewards apply based on successful billing cycles
* The reward becomes active starting from the specified cycle number
* For example, if set to "After 3 cycles", the reward applies on the 4th, 5th, 6th orders, etc.
* Customers see their reward status in the customer portal
* Failed billing attempts don't count toward the cycle total

## Customer Portal Display

Customers can view their reward progress in the subscription management portal:

* Current billing cycle number
* Rewards available on their plan
* Number of orders remaining until reward eligibility
* Reward message when eligible

## Email Template Placeholders

You can include reward information in your customer email templates using these placeholders:

* `{{reward_message}}` - Human-readable message about the reward status
* `{{reward_eligible}}` - "yes" or "no" indicating if next order qualifies
* `{{reward_cycles_remaining}}` - Number of orders until reward eligibility
* `{{current_cycle}}` - Customer's current billing cycle number

### Example Email Template

```html theme={null}
<p>Hi {{customer_first_name}},</p>

<p>Your next order is scheduled for {{next_billing_date}}.</p>

<p>You're on cycle {{current_cycle}} of your subscription!</p>

{{#if reward_eligible}}
  <p><strong>Great news!</strong> {{reward_message}}</p>
{{else}}
  {{#if reward_cycles_remaining}}
    <p>Just {{reward_cycles_remaining}} more order(s) until you unlock: {{reward_message}}</p>
  {{/if}}
{{/if}}
```

## Best Practices

1. **Set Realistic Thresholds**: Don't make customers wait too long for rewards
2. **Communicate Clearly**: Make sure customers know about rewards when they sign up
3. **Track Performance**: Monitor which rewards drive the most retention
4. **Test Different Rewards**: Try various reward types to see what resonates
5. **Consider Your Margins**: Ensure rewards are sustainable for your business

## API Integration

Reward data is available through the customer portal API endpoint at `/apps/subscription/portal`:

```json theme={null}
{
  "rewards": {
    "gid://shopify/SubscriptionContract/123": {
      "currentCycle": 3,
      "hasReward": true,
      "rewardType": "percentage_off",
      "rewardAfterCycle": 3,
      "cyclesUntilReward": 0,
      "isEligible": true,
      "rewardMessage": "15% discount applied (cycle 4 reward)"
    }
  }
}
```

## Troubleshooting

### Reward Not Applying

* **Check cycle count**: Verify the customer has reached the required number of cycles
* **Review billing history**: Ensure all billing attempts were successful
* **Confirm plan configuration**: Double-check the reward is enabled and configured correctly

### Customer Can't See Reward Status

* **Portal access**: Ensure customer has access to the subscription portal
* **Plan configuration**: Verify the reward is enabled on their specific plan
* **Cache**: Try refreshing the portal page

## Technical Notes

* Rewards are tracked automatically based on successful billing attempts
* Cycle counting starts from the first successful billing
* The reward system logs all eligibility checks for audit purposes
* Reward data is cached for performance and updated on each billing cycle


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.