> For the complete documentation index, see [llms.txt](https://docs.perkville.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkville.com/guides/membership-upgrades.md).

# Membership upgrades

Set up membership tiers to reward active members and encourage upgrades.

Membership tiers let you group membership types and automatically award points, instant rewards, or both. Customers can earn rewards for their current tier and any lower tiers they have not already earned, so joining at a higher tier is just as rewarding as upgrading over time.

Your business must use memberships in Perkville, with membership types and statuses supplied through your integration or API connection. For a feature overview, see [Membership tiers](https://docs.perkville.com/features/earning-rules/membership-tiers.md).

{% hint style="info" %}
Only **active memberships** qualify for tiers and tier rewards. Inactive memberships and memberships with an unknown status do not qualify. If a customer has multiple active memberships, Perkville uses the highest qualifying active tier.
{% endhint %}

## Membership types as tiers

Group similar membership types into one tier to keep your program easy to manage. For example, seven membership types could be organized into three tiers:

| Membership tier | Membership types                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------------ |
| Basic (Tier 1)  | Bronze unlimited; Bronze unlimited - zero down; Silver Sneakers; Teachers and veterans unlimited |
| Silver (Tier 2) | Silver unlimited; Silver unlimited - zero down                                                   |
| Gold (Tier 3)   | Gold unlimited                                                                                   |

Membership types are identified by both their name and their source system. If the same name appears under two systems, select the appropriate entry for each.

## Tiered rewards

Create one membership tier earning rule for each tier. Enter only the **additional reward for that tier**, not the combined value of all tiers below it.

Each customer can earn each tier's reward **once ever**. Changing membership types, downgrading, canceling, or returning to a previously earned tier does not award that tier again.

| Membership tier | Additional points | Total points after earning this and all lower tiers |
| --------------- | ----------------- | --------------------------------------------------- |
| Basic (Tier 1)  | 100               | 100                                                 |
| Silver (Tier 2) | 150               | 250                                                 |
| Gold (Tier 3)   | 250               | 500                                                 |

**Example 1:** A new customer with an active Gold membership receives 100 points for Basic, 150 for Silver, and 250 for Gold: **500 points total**, assuming all three rewards are active and the customer meets their eligibility requirements.

**Example 2:** A customer who already earned Basic and Silver has received 250 points. Upgrading to an active Gold membership awards only Gold's additional **250 points**.

The same once-ever behavior applies to instant rewards attached to a tier. Inactive tiers do not award rewards. Positions do not need to be consecutive: if only tiers 1 and 3 are active, a qualifying tier 3 customer can earn those two rewards.

## Set up membership tiers

Open **Settings → Loyalty Program → Membership tiers**. Membership tiers are available only when memberships are enabled for your business.

{% hint style="warning" %}
Keep **Enable membership tier rewards** set to **No** until you finish configuring all tiers. Pause it again before making a series of changes. Otherwise, customers may qualify under an intermediate configuration before you finish editing.
{% endhint %}

1. Review the shared **Tier settings**, described below.
2. Select **Add membership tier**.
3. Set **Active** and enter a **Title**. The title names the earning rule; you do not need a separate tier name.
4. Select the **Qualifying membership types**, or configure a fallback tier.
5. Set the **Tier position**. Start at 1 for your entry-level tier and use higher numbers for more premium tiers.
6. Set the additional **points and/or instant rewards** for this tier.
7. Review eligible locations and optional settings, then save.
8. Repeat for the remaining tiers. When everything is ready, turn **Enable membership tier rewards** on and save the shared settings.

Each position can be used only once, including positions held by inactive tiers. The form lists other active tiers to help you choose a position.

### Fallback tier

A fallback tier is useful for an entry-level reward that should include newly added membership types automatically.

Turn on **Use as the fallback for unassigned membership types**. It includes membership types that are not assigned to another active tier. Use **Excluded membership types** to leave specific types out; leave that selection blank to include all unassigned types.

Only one fallback tier can be configured. An assignment to an inactive tier does not prevent a membership type from matching an active fallback tier. Membership types assigned to inactive tiers can also be reassigned when editing another tier.

Fallback exclusions affect direct qualification only. A customer who qualifies for a higher tier can still earn the fallback tier's unearned reward as a lower-tier reward.

### Locations

Tier rewards prefer the customer's **active home location**. Use **Eligible locations** to select where the reward may be awarded.

* **Restrict to home location — Yes:** The customer must have an active home location included in the eligible locations. No fallback location is used.
* **Restrict to home location — No:** If there is no active home location, Perkville uses the customer's last transaction location, then the business's primary location. The location used must be eligible.

An active home location outside the selected locations does not cause Perkville to try another location.

### Display and other options

Use **Category** and **Display order** to arrange tier earning rules on the customer-facing loyalty program. **Tier position** determines eligibility and lower-tier rewards; it does not determine display order or automatically group the rules into a separate section.

Optional settings include description, fine print, location locking, referral completion, transaction emails, and visibility. **Hide perk** hides the rule from customers but does not stop eligible customers from earning it. To pause awards, deactivate the individual tier or disable tier rewards for the business.

## Shared tier settings

These settings apply to all tiers.

### Enable membership tier rewards

Turn this off to pause all tier rewards while retaining your configuration and award history. When disabled, tier earning rules are also hidden from customer-facing views and the API.

Turning it on requests a check of eligible members under your current settings. Saving a tier while this setting is off does not enable awards, even if the individual tier is active.

### Qualification date

**Qualify new memberships and membership changes on or after** lets you limit eligibility to membership records added to Perkville, or whose type or status changed, on or after a date.

**Leave it blank** to include existing eligible members based on their current active memberships. They do not need a new membership or membership change.

The date is based on when Perkville receives or observes the membership event. It is not a reliable way to restrict rewards by the membership's original purchase date. Importing old memberships after the cutoff can make them eligible. For older records without a tracked membership-change date, Perkville uses the record's last-updated date.

### Apply award when the member joins the loyalty program

* **Yes:** Customers must join the loyalty program before receiving tier rewards, even if your program normally allows earning before enrollment.
* **No:** Your normal loyalty program rules apply. If those rules require enrollment to earn, customers still need to join.

When a customer joins, Perkville checks their current active memberships and the current tier configuration. A membership that was canceled or downgraded before enrollment does not preserve entitlement to its former tier reward. Rewards use the configuration in effect when they are delivered.

## When rewards are processed

Membership and enrollment changes trigger checks as they are processed. Changes to shared tier settings or individual tiers request a broader check during subsequent hourly processing, provided tier rewards are enabled.

Enabling the feature does not award everyone during the settings save. The hourly process picks up the requested check and works through customers in batches. Completion time depends on the number of customers and processing availability.

Scheduled recovery also revisits recent activity. A completed scan does not mean every member received a reward: customers must still satisfy membership, enrollment, location, and other earning requirements.

## Convert an existing earning rule

If you already award membership rewards through a standard earning rule, you can convert it instead of creating a replacement. This retains the rule's **ID and transaction history**.

1. Open the standard earning rule from **Loyalty Program → Rules & Activities**.
2. Select **Convert to membership tier** below the form. The Membership tiers page also links you to existing earning rules.
3. Configure the membership types, position, reward, and optional settings.
4. Review and confirm the conversion.

Conversion sets the earning limit to **once ever**, even if the old limit allowed multiple awards. Existing qualifying awards of the same rule count toward that limit, so those customers do not receive the tier reward again.

{% hint style="warning" %}
After conversion, Perkville controls tier qualification and awarding. Staff and API clients can no longer award the rule directly.

All saved integration mappings for that rule are removed, including inactive mappings. Purchase, check-in, and other integration events will no longer award it. Connect those events to a different earning rule if needed.

[Middle](https://www.middle.app/) workflows are not disabled automatically. After conversion, direct award requests from the previous workflows will be rejected. Contact Support before converting if you need help coordinating the transition.
{% endhint %}

**Email** [**support@perkville.com**](mailto:support@perkville.com) **as soon as conversion is complete** so our team can turn off the Middle workflows that handled your previous membership tier awards. Include your business name, **Perkville business ID from your Perkville dashboard**, and the earning rules you converted.

For general information about earning rules, see [Award points](https://docs.perkville.com/features/earning-rules.md).

## If a customer has not received a reward

Check that:

* Tier rewards are enabled for the business and the individual tier is active.
* The membership status is active, with the expected type and source system.
* The membership meets the qualification date, if one is set.
* The customer meets enrollment and normal loyalty program earning requirements.
* Their home or fallback location meets the tier's location settings.
* They have not already earned that tier or received a qualifying award from a converted rule.
* The hourly check has had time to process a configuration change.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.perkville.com/guides/membership-upgrades.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
