---
title: Membership Tiers
slug: oms/membership-tiers
docTags: 
createdAt: 2026-02-06T09:02:42.834Z
---

Admins can upgrade or downgrade a customer's membership tier mid-billing cycle. The system automatically calculates prorated charges or refunds based on the remaining days in the cycle.

**Feature flag:** SUBSCRIPTION\_MEMBERSHIP\_UPGRADE disabled by default

## Setup

### 1. Create an Option Type for Tiers

Go to **Products > Option Types** and create a new option type:

- **Name:** membership-tier
- **Presentation:** Membership Tier
- Add option values for each tier (e.g., basic, premium, vip)

### 2. Create a Membership Product

Go to **Products > New Product** and create a single product that represents your membership:

- **Name:** e.g., Membership
- **Option Types:** assign the membership-tier option type created above

### 3. Create Variants for Each Tier

Under the membership product, create one variant per tier:

- **Basic** — Price: $20.00, Option: basic
- **Premium** — Price: $36.00, Option: premium
- **VIP** — Price: $50.00, Option: vip

All tiers must be **variants of the same product**. The system detects tier changes by checking that the old and new variants share the same product\_id.

## Upgrading a Tier

When you change a subscription to a higher-priced tier, the customer is charged immediately for the prorated difference.

| Current membership tier                                                                                                            | Replace existing variant with higher tier                                                                                          |
| ---------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| <br />:inlineImage[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/bk7ZvOmN1ss9pTCUtyHNO_image.png" alt caption} | <br />:inlineImage[]{src="https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/EXS08_zLwdEn7WVdQsLG__image.png" alt caption} |
|                                                                                                                                    |                                                                                                                                    |
|                                                                                                                                    |                                                                                                                                    |

Once you update the subscription, an order will be created with the payment.

![](https://api.archbee.com/api/optimize/TmutqdeXiIw-V3gBZXVjd/EEPtg9XovUNOJSf4uNl8Z_image.png)

## Downgrading a Tier

When you change a subscription to a lower-priced tier, you can choose how to handle the refund:

- **No refund** - Customer keeps credit for next cycle
- **Issue store credit** - Creates store credit on the customer's account
- **Refund to original payment method** - Refunds to the card used for the subscriptio