# About the Plans API

Using the Plans API, you can create and manage pricing plans.

This includes building a customized membership plan experience, including implementing a customizable pricing page where customers can view the plans, including their perks, prices, and other features including free trials, purchase limitations, and more. 

With the Plans API, you can:

- Create and update plans. This includes:

    - Setting up pricing models for plans, such as free, one-time payment, and recurring payments (subscriptions). 
    
    - Determining if pricing plans should have a duration or be valid until canceled by a customer. 
    
    - Limiting plans so they can be purchased only 1 time by a single customer. By default, customers can make unlimited purchases of the same plan. 
    
  Note that updating the properties of an existing pricing plan doesn't affect any current orders or purchases of the plan. Existing orders retain their existing terms and pricing.
  
- Get, list, and query plans. 

- Change the visibility, availability, and accessibility of a plan.

- Get statistics about plans. 

- Archive plans. 

- Set or clear the primary plan. This determines if a plan is highlighted with a custom ribbon when viewing the plans on a site.

## More about plans

It's important to explore the types of plans available and other specifications, such as payment options and purchasing constraints.

### Pricing plan types

Pricing plans can be: 

- **Free plans**. There is no charge to the site visitor or member.

- **One-time payment plans**. The site visitor or member is charged once. These plans can be set to expire or continue indefinitely until they cancel.

- **Recurring plans**. The site visitor or member is charged at predefined intervals (such as weekly, monthly, yearly). These plans can be set to expire or continue indefinitely until they cancel the subscription. Recurring plans can have free trial days.

### Free trial plans
Recurring plans can be set to have free trial days using the plan's `freeTrialDays` property.

During free trial days, site visitor and members can cancel the plan and they won’t be charged.

Free trial days are applied only once per site visitor or member for a plan. This means that if a plan with a free trial was purchased once, the second time they purchase it, the free trial days aren't applied. In this case, the site visitor or member is charged for the plan right away.

### Purchase limitations

Some plans can be purchased only a limited number of times by a single site visitor or member based on the value of the plan's `purchaseLimitations` property. 

If the plan is updated, the limit is checked by the current plan details. For example, let's assume a plan's purchase limit was initially set to 1 and a site visitor or member purchased the plan. If later the limit is updated to 2, they can still purchase the same plan a second time.

### Plan expiration

A plan can be active for specified periods of time from the date of purchase. The active period is established in the same intervals as the payment periods (weeks, months, years). Plans can also be defined so they never expire (meaning, the plan continues indefinitely until the member cancels). This is true for both one-time and recurring plans.

### The slug property

Slugs are used to support [dynamic pages](fallback::https://support.wix.com/en/article/cms-setting-up-a-dynamic-item-page). 

A slug is generated on a plan's creation and is updated when a plan's name is updated. For example, if the plan's name is "Test Plan," the generated slug is "test-plan." If a plan already exists with a slug "test-plan" for the site, a number is appended to it. The slug becomes "test-plan-1". 


## Before you begin

It's important to note the following point before starting to code:

- This API requires [Wix Pricing Plans](fallback::https://support.wix.com/en/article/pricing-plans-an-overview) to be installed on a site calling the API. 

## Terminology

- **Plan**: A membership plan or package, offering bundles of features or “perks.” 
  - A **free plan** can be purchased free of charge.
  - A **one-time plan** can be purchased with a single payment.
  - A **recurring plan** charges the customer on a weekly, monthly, or yearly basis for a selected duration of time.
  
- **Primary plans**: Plans that are labeled with a ribbon that is customizable on a site.

- **Archived plans**: Plans that can no longer be purchased or edited, but existing plan holders can still enjoy purchased membership and continue to be charged until canceled or expired.

- **Hidden plans**: Plans that are not currently visible to customers. Hidden plans may still be sold manually to customers.

- **Free trial**: A feature allowing for the trying out of the perks of the plan for a selected amount of days before the first charge. Relevant for recurring plans.

- **Plan Policy**: The definition of terms and conditions for the customer. A plan's policy can be displayed on a site's checkout page.

# Filter and Sort

Select endpoints allow sorting results by field. Use `"order": "ASC"` to sort results in ascending order, and `"order": "DESC"` to sort in descending order.

For example, to sort plans by created date in descending order:

```json
"sort": { "fieldName": "createdDate", "order": "DESC" }
```

Refer to the following tables to check which fields support sorting.

## Query Public Plans
[//]: # (https://bo.wix.com/wix-docs/rest/drafts/pricing-plans/plan-v2/query-public-plans)

| Field     | Description       | Query Filter Operators                                  | Sorting | 
|-----------|-------------------|---------------------------------------------------------|---------|
| id   |     Plan ID   |   $eq, $ne, $hasSome                      |  |         
| primary  | Whether the plan is marked as primary, and highlighted in the site with a custom ribbon |     $eq, $ne             | Allowed |        
| slug     | URL-friendly version of the plan name. Unique across all plans in the same site        |  $eq, $ne, $startsWith, $endsWith, $contains | Allowed | 
| createdDate       | Date plan was created           |    $eq, $ne, $gt, $ge, $lt, $le, $between    | Allowed |         
| updatedDate     |    Date plan was updated               | $eq, $ne, $gt, $ge, $lt, $le, $between   | Allowed |

# Plans: Sample Use Case & Flow

This article shares a possible use case you could support, as well as a sample flow that could support the use case. This can be a helpful jumping off point as you plan your implementation.

## Sync available pricing plans to an external system

Wix users can keep their external platform up to date with the pricing plans they offer. For example, 
when a site owner adds a new pricing plan to a Wix site, the external platform will have the new plan available for purchase. 

Use this flow to implement a sync from a Wix site to an external system:
1. Create a mapping from pricing plans to the plans stored on an external app using a common field, like name. Store this mapping on your app's server.
1. Listen for any changes to which pricing plans are available with the [Plan Created event](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::a58b05ec-66f5-4e67-957f-49cfd43978b5slug::plan-created*fallback::https://dev.wix.com/api/rest/wix-pricing-plans/pricing-plans/plans/plan-created-webhook) and the [Plan Archived event](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::a58b05ec-66f5-4e67-957f-49cfd43978b5slug::plan-archived*fallback::https://dev.wix.com/api/rest/wix-pricing-plans/pricing-plans/plans/plan-archived-webhook).
1. When one of the events is triggered you receive the details of the pricing plan in `createdEvent.entity` if a plan was created or `actionEvent.body.plan` if a plan was archived.
1. Use these pricing plan details to add the new plan to, or remove the archived plan from, your external app.

# Plans V1: Migration Guide

This guide helps you migrate from Plans V1 to the Plans V3 API. Plans V1 will be removed on December 31, 2025. 

## Key changes

Plans V3 is a new and improved version of V1. The API has been standardized according to the latest Wix API design rules.

The following methods don't have a 1\:1 replacement and need to be replaced with alternative methods:

- **List Public Plans:** To retrieve public plans, call Query Plans or Search Plans from the Plans V3 API. In the `filter` object, set the `visibility` field to `PUBLIC` and the `archived` field to `false`.
- **Query Public Plans:** To retrieve public plans, call Query Plans or Search Plans from the Plans V3 API. In the `filter` object, set the `visibility` field to `PUBLIC` and the `archived` field to `false`.
- **Set Plan Visibility:** To update plan visibility, call Update Plan from the Pricing Plans V3 API and modify the `visibility` field value.
- **Make Plan Primary:** To set a plan as primary, first call Query Plans from the Plans V3 API and filter by `primary: true`. For the filtered plans, call Bulk Update Plans to set the `primary` field to `false`. Then set the `primary` field to `true` for the new plan.
- **Clear Primary:** To remove a plan's primary status, call Query Plans from the Plans V3 API and filter by `primary: true`. For the filtered plans, call Bulk Update Plans to set the `primary` field to `false`.
- **Archive Plan:** To archive a plan, call Update Plan from the Plans V3 API and set the `archived` field to `true`.

## Support

- [Plans V3 API](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/introduction)
- Contact Wix Developer Support for additional assistance.