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.

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:

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.

Did this help?

Setup

To use the Plans API, install the @wix/pricing-plans package using npm or Yarn:

Copy

or

Copy

Then import { plans } from @wix/pricing-plans:

Copy
Did this help?

archivePlan( )

Archives a single plan. When a plan is archived, it's no longer visible as a public plan that can be chosen by site members or visitors. This is because the plan's public property is automatically set to false. Archived plans can't be purchased or reactivated. Plan archiving doesn't impact existing orders made for the plan. All orders for the plan are still active and keep their perks, payment options, and terms. Wix users can see archived plans in a site's dashboard under Pricing Plans -> Archived Plans.

Note: An attempt to archive an already-archived plan throws an error.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

ID of the active plan to archive.

Returns
Return Type:Promise<ArchivePlanResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

clearPrimary( )

Sets all pricing plans as not primary. When viewing pricing plans on a site, no plan is highlighted with a customizable ribbon.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Learn more about app permissions.
Method Declaration
Copy
Request
This method does not take any parameters
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createPlan( )

Creates a pricing plan. The specified plan object must contain a pricing model. A pricing model can be 1 of the following:

  • A subscription: A subscription with recurring payments and how often the plan occurs. Subscriptions can have free trial days.
  • A plan that doesn't renew: A single payment for a specific duration that doesn't renew.
  • An unlimited plan: A single payment for an unlimited amount of time (until canceled). Pricing plans are available to the Wix user in the Pricing Plans section in a site's dashboard.
Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
planPlanRequired

Information for the plan being created.

Returns
Return Type:Promise<Plan>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getPlan( )

Retrieves a pricing plan by ID.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Read Pricing Plans
Manage Events
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
_idstringRequired

Plan ID.

Returns
Return Type:Promise<Plan>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

getPlanStats( )

Gets statistics about the pricing plans. Currently provides only the total number of pricing plans, including archived plans.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Read Pricing Plans
Manage Events
Learn more about app permissions.
Method Declaration
Copy
Request
This method does not take any parameters
Returns
Return Type:Promise<GetPlanStatsResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listPlans( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a list of up to 100 pricing plans (including public, hidden, and archived plans).

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Pricing Plans
Read Pricing Plans
Manage Events
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsListPlansOptions

Options for filtering and paging the list of plans.

Returns
Return Type:Promise<ListPlansResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

listPublicPlans( )

Retrieves a list of up to 100 public pricing plans. Public plans are visible plans that are available to site visitors and can be purchased.

Permissions
Manage Bookings Services and Settings
Manage Orders
Read Orders
Read Pricing Plans
Manage Events
Access Verticals by Automations
Set Up Automations
Manage Pricing Plans
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
Method Parameters
optionsListPublicPlansOptions

Options for filtering and paging the list of public plans.

Returns
Return Type:Promise<ListPublicPlansResponse>
JavaScript
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?