# About the Plans V3 API

The Plans V3 API allows you to create and manage pricing plans that determine charges for site content and services. With this API, a Wix user can grow their business by selling bundles and memberships. The Wix user can decide how long a plan lasts before it expires or renews and what perks are offered with the plan.  

With the Pricing Plans V3 API, you can:

- [Create](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/create-plan) a pricing plan.
- [Update](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/update-plan) an already created plan.
- [Retrieve](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/query-plans) plans.
- [Count](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/count-plans) plans by the filter.

### Types of plans

You can create 3 main type of plans:
- **Recurring**: A subscription plan with recurring payments, and set the plan to recur daily, weekly, monthly, or yearly. Recurring payments offer more flexible terms to clients without a large, up-front commitment. The recurring plan is defined with the `billingCycle` object.
    >**Note:** To accept recurring payments, a Wix user needs to [set up a payment provider that supports recurring payments](fallback::https://support.wix.com/en/article/accepting-recurring-payments). 
- **One-time**: A one-time plan that lasts for the time period you choose. Charges a single upfront fee.
- **Free plan**: Let customers try the services before committing to a full membership plan or package by creating a free promotional plan that customers can book only once. To create a free plan, set the `flatRate` value to `0`.

### Free trials

Let potential customers get to know the products, services and content by offering them a free trial period at the beginning of their plan or package. You choose the length of the free trial period to suit the plan or package. Free trials are only applicable for recurring plans, and when the free trial is over, the customer's first billing cycle begins. The free trial can only be used once, and if canceled, the customer can continue to enjoy plan benefits until the free trial ends.

### Plan duration

Wix users can determine how long plans remain active after purchase. Plan duration can be set using the same time units as billing cycles (days, weeks, months, or years). Wix users can also create plans that never expire, continuing indefinitely until customers cancel. This applies to both one-time and recurring plans.

## Before you begin

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

- Install the **Wix Pricing Plans** app from the [Wix App Market](fallback::https://www.wix.com/app-market/web-solution/pricing-plans).
- Currently, you can have only 1 pricing variant and a strategy.
- A Wix user must configure site currency before creating plans.
- To sell plans, a Wix user must [connect a payment provider](fallback::https://support.wix.com/en/article/pricing-plans-setting-up-payments) on the site.
- In this API perks act as a list for marketing purposes. To create actual benefits, see [Benefit Programs](fallback::https://dev.wix.com/docs/rest/business-solutions/benefit-programs/introduction).

## Use cases

- [Sync pricing plans across multiple systems](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/sample-flows)
- [Import plans from external systems](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/sample-flows)


## Terminology

- **Plan**: A pricing plan that defines what customers can purchase and how they'll be charged, including billing terms, pricing, and features.
- **Pricing variant**: Combines billing terms with pricing strategies to offer different billing options for the same benefits. For example, a plan might offer monthly billing at $50 or yearly billing at $500. Currently limited to 1 variant per plan.
- **Pricing strategy**: Determines how much customers pay. Currently supports flat rate pricing only, where customers pay a fixed amount per billing cycle.
- **Billing terms**: Configuration that defines when billing starts, how often customers are charged (billing cycle), and when the plan ends.
- **Perks**: Benefits or features included with the plan, displayed to customers as a list of what they get. To configure actual 

@sdk_package_setup

# Plans V3: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. These use cases can be helpful jumping off points.

## Sync pricing plans across multiple systems

Your app can synchronize plan data between Wix and external systems to maintain consistency across platforms.

To sync pricing plans with an external database:

1. Call [Query Plans](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/query-plans) to retrieve all existing plans from Wix.

2. Store the plan data in your external system, ensuring you save the plan ID and revision for future updates.

3. Set up event listeners for [Plan Created](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/plan-created), [Plan Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/plan-updated), and [Plan Deleted](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/plan-deleted) events to automatically sync changes.

4. When receiving a [Plan Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/plan-updated)` event, use the revision number to avoid conflicts and update only the changed fields in your external system.

## Import plans from external systems

You can bulk create plans in Wix from data stored in external systems, useful for migrating from other platforms.

To import plans from an external database:

1. Prepare your plan data as an array of plan objects, ensuring each has the required fields (name, pricing variants, billing terms).

2. Iterate through your plan array, calling [Create Plan](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans/plans-v3/create-plan) for each plan. To comply with rate limits, ensure requests are sent at least 1 second apart.

3. Handle any validation errors appropriately, such as missing currency configuration or invalid billing cycles.

4. After import, set up ongoing synchronization using domain events to keep both systems in sync.

# Plans V3: Supported Filters and Sorting

The following table shows field support for filters and sorting for the schedule item object:

| Field              | Supported Filters                            | Sortable |
| ------------------ | -------------------------------------------- | -------- |
| `id`               | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`, `$ge` | Sortable |
| `createdDate`      | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$gt`, `$lt`, `$le`, `$ge` | Sortable |
| `updatedDate`      | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$gt`, `$lt`, `$le`, `$ge` | Sortable |
| `slug`             | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`,`$ge` | Sortable |
| `formId`           | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`,`$ge` | Sortable |
| `name`             | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`,`$ge` | Sortable |
| `pricingVariants.id`| `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`,`$ge` | Sortable |
| `pricingVariants.name`| `$eq`, `$ne`, `$exists`, `$in`, `$hasSome`, `$startsWith`, `$gt`, `$lt`, `$le`,`$ge` | Sortable | 
| `pricingVariants.pricingStrategies.flatRate.amount`| `$hasSome`, `$hasAll` | Sortable | 
| `visibility`       | `$eq`, `$ne`, `$exists`, `$in`, `$hasSome` | Sortable |

Field	Supported Filters	Sort
`pricingVariants.pricingStrategies.flatRate.amount`	`$hasSome`, `$hasAll`	Sort: ✗
`id`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`createdDate`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$lt`, `$lte`, `$gt`, `$gte`	Sort: `ASC`, `DESC`
`updatedDate`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$lt`, `$lte`, `$gt`, `$gte`	Sort: `ASC`, `DESC`
`name`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`visibility`	`$eq`, `$ne`, `$exists`, `$in`, `$any`	Sort: `ASC`, `DESC`
`formId`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`pricingVariants.id`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`pricingVariants.name`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`slug`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`
`termsAndConditions`	`$eq`, `$ne`, `$exists`, `$in`, `$any`, `$begins`, `$gt`, `$lt`, `$lte`, `$gte`	Sort: `ASC`, `DESC`