# 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. You can decide how long a plan lasts, how much it costs, whether the buyer pays once upfront or makes recurring payments, and what perks the plan offers.

With the Plans V3 API, you can:

- Create and manage pricing plans.
- Set the pricing and billing terms of plans.
- Set a plan's duration.
- Set free trial periods for plans.
- Manage customers' ability to view, subscribe to, or cancel their subscription to a plan.

## Types of plans

The most common types of plans are:
- **One-time**: A plan that charges a single upfront payment and lasts for the time period you choose.
- **Recurring**: A plan with recurring payment. You can set the plan to recur daily, weekly, monthly, or yearly. Recurring payments offer more flexible terms, without a large up-front commitment.
- **Free plan**: A plan that requires no payment. Typically available only once and used for promotions or as free trials for one-time plans. For recurring plans, you can set built in [free trial](fallback::#free-trials) periods after which the plan starts billing the buyer automatically.

>**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). 

## Free trials

You can set up a free trial period for recurring plans. When the buyer subscribes to the plan for the first time, they gain access to the plan's benefits until the end of the free trial period. The buyer keeps their access to those benefits even if they cancel their subscription during that time. At the end of the trial period, the first billing cycle begins. A buyer can only benefit from the trial period of a specific plan once.

To add a free trial to a plan you create, specify a number of days in `freeTrialDays`.

## Plan duration

You can determine how long plans remain active after the buyer subscribes to them. You set a plan's duration using the same time units as billing cycles: days, weeks, months, or years. You can also create plans that never expire, continuing indefinitely until the buyer cancels.

- To limit the duration of a plan, set its `endType` to `CYCLES_COMPLETED` and specify a number of cycles in `cyclesCompletedDetails.billingCycleCount`.
- To create a plan that never expires, set its `endType` to `UNTIL_CANCELLED`.

## Customer permissions

You can control which actions customers can perform themselves for a specific plan. Wix users can still perform these actions on a customer's behalf regardless of these settings.
- View the plan in the **Plans & Pricing** page. Determined by the plan's `visibility`.
- Subscribe to the plan. Determined by the plan's `buyable`.
- Cancel their subscription to the plan. Determined by the plan's `buyerCanCancel`.

## Tags

You can assign tags to plans to classify them and filter by them later. Tags are managed by the [Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/tags), and a plan stores only tag IDs, not tag names. Assign a tag to a plan only after the tag exists. When you create or list tags for plans, pass `wix.pricing_plans.v3.plan` as the `fqdn`.

A plan has two separate tag lists:

- **Public tags**: Visible to anyone who can read the plan, including site members and visitors.
- **Private tags**: Visible only to callers with the `PRICING_PLANS.PLAN_READ` permission. Use these for internal classification you don't want to expose on the live site.

A plan can hold up to 100 tags in each list.

To update tags:

- [Bulk Update Plan Tags](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/bulk-update-plan-tags) assigns and unassigns tags on up to 100 plans by ID, and returns the result for each plan.
- [Bulk Update Plan Tags By Filter](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/bulk-update-plan-tags-by-filter) assigns and unassigns tags on every plan matching a filter. An empty filter matches all plans. The update runs asynchronously, so the response returns a `jobId` instead of per-plan results.
- [Update Plan](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/update-plan) replaces the plan's entire tag list. Use the bulk methods to add or remove individual tags without overwriting the rest.

Both bulk methods accept `assignTags` and `unassignTags`. At least one of them must be non-empty, otherwise the call fails with `EMPTY_ASSIGN_AND_UNASSIGN_LISTS`. A tag listed in both is assigned.

To find plans by tag, filter on `tags.publicTags.tagIds` or `tags.privateTags.tagIds` with `$hasSome` or `$hasAll`. See [Supported Filters and Sorting](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/filter-and-sort).

Every tag change emits two events. [Plan Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/plan-updated) fires with the plan's new state, and [Plan Tags Modified](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/plan-tags-modified) fires with the tags that were assigned and unassigned. Subscribe to Plan Tags Modified when you only care about tag changes and want the delta rather than the full plan.

## Before you begin

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

- The Wix user must install the [Wix Pricing Plans](fallback::https://www.wix.com/app-market/web-solution/pricing-plans) app on their site.
- Currently, a plan can have only have 1 `pricingVariant` and 1 `pricingStrategy`.
- The Wix user must [set the site's currency](fallback::https://support.wix.com/en/article/setting-your-currency-for-accepting-payments).
- 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

- [Import plans from external systems](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3b393df5-232e-4c6e-850d-5a19084a77beslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/sample-flows)
- [Sync pricing plans across multiple systems](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3b393df5-232e-4c6e-850d-5a19084a77beslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/sample-flows)
- [Organize plans with tags](portalId::d1972c09-74e2-4d36-a6f2-54e3310d4ad9resourceId::3b393df5-232e-4c6e-850d-5a19084a77beslug::sample-flows*fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/pricing-plans/plans-v3/sample-flows)


## Terminology

- **Plan**: A pricing plan that members can subscribe to. Includes promotional data, pricing configurations, and other settings. Wix users can track and manage plans in the dashboard under **Catalog > Pricing Plans**.
- **Customer**: A member who can view and subscribe to plans.
- **Buyer**: A customer who subscribes to a plan.
- **Subscription**: The act of purchasing a plan. Wix users can track and manage subscriptions in the dashboard under **Sales > Subscriptions**.
- **Pricing variant**: Combines billing terms with pricing strategies to offer different billing options for a benefits. For example, a plan might offer monthly billing at $50 or yearly billing at $500. A plan can only have 1 variant.
- **Pricing strategy**: Determines how much customers pay. 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**: Names of benefits included with the plan. For display only. To configure benefits, see [Benefit Programs](fallback::https://dev.wix.com/docs/rest/business-solutions/benefit-programs/introduction).
- **Tag**: A label you can assign to a plan to classify it and filter by it. Tags are either public, readable by anyone who can read the plan, or private, readable only with the `PRICING_PLANS.PLAN_READ` permission.

@sdk_package_setup

# Plans V3: Sample Flows

This article presents possible use cases and corresponding sample flows that you can support. It provides a useful starting point as you plan your implementation.

## Import plans from external systems

You can create plans using data stored in external systems. This is useful when migrating to Wix from another platform or maintaining data across multiple platforms.

To import plans from an external system:

1. Prepare your plan data as an array of plan objects, ensuring each has the required fields: `pricingVariants` and `visibility`.

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

3. [Set up ongoing synchronization](fallback::#sync-pricing-plans-across-multiple-systems) using events to keep both systems in sync.


## Sync pricing plans across multiple systems

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

To sync pricing plans with an external system:

1. Call [Query Plans](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-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's `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-v3/plan-created), [Plan Updated](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/plan-updated), and [Plan Deleted](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/plan-deleted) events to automatically sync changes.

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

## Organize plans with tags

You can tag plans to group them by campaign, audience, or lifecycle stage, then retrieve each group without hardcoding plan IDs.

To organize plans with tags:

1. Create the tags you need with the [Tags API](fallback::https://dev.wix.com/docs/api-reference/business-management/tags/introduction), passing `wix.pricing_plans.v3.plan` as the `fqdn`, and store the returned IDs. A plan references tags by ID only.

2. Call [Bulk Update Plan Tags](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/bulk-update-plan-tags) with up to 100 plan IDs, passing each tag ID in either `assignTags.publicTags` or `assignTags.privateTags`. Site members and visitors can read public tags, so use private tags for internal classification. Check `itemMetadata.success` on each result, since individual plans can fail while the rest succeed.

3. To tag plans you can't enumerate, call [Bulk Update Plan Tags By Filter](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/bulk-update-plan-tags-by-filter) with a filter instead of IDs. The response returns a `jobId` rather than per-plan results, so poll the job to confirm completion.

4. Retrieve a group by calling [Query Plans](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/query-plans) with a `$hasSome` filter on `tags.publicTags.tagIds` or `tags.privateTags.tagIds`. Use `$hasAll` to require every tag in the list.

5. To keep an external system in sync, subscribe to [Plan Tags Modified](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/plan-tags-modified). It delivers the assigned and unassigned tags for each change, so you don't have to diff the plan's full tag list yourself.

> **Note:** Don't use [Update Plan](fallback::https://dev.wix.com/docs/rest/business-solutions/pricing-plans/plans-v3/update-plan) to add a single tag. It replaces the plan's whole tag list, which drops tags set by other flows.

# Plans V3: Supported Filters and Sorting

The following table shows field support for filters and sorting for the plan 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 |
| `tags.publicTags.tagIds` | `$hasSome`, `$hasAll` | Not sortable |
| `tags.privateTags.tagIds` | `$hasSome`, `$hasAll` | Not sortable |

> **Note:** Filtering by `tags.privateTags.tagIds` requires the `PRICING_PLANS.PLAN_READ` permission. Without it, private tags are omitted from responses and can't be used in filters.