Setup

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

Copy
1
npm install @wix/pricing-plans

or

Copy
1
yarn add @wix/pricing-plans

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

Copy
1
import { plans } from '@wix/pricing-plans'
Was this helpful?
Yes
No

About Plans

Use the Pricing Plans Plans API to create and manage your pricing plans. You can build a customized membership plan experience based on the plans that you create and manage with Plans.

With the Plans API, you can:

  • Create and update plans.
  • List and query plans.
  • Set plans to be public or hidden.
  • Archive plans.
  • Set a plan to be the primary plan, or clear the primary plan status.
  • Get statistics about plans.
  • Arrange the order in which plans are displaid.

Updating the properties of a pricing plan does not affect any current orders or purchases of the plan. Any existing orders retain their existing terms and pricing.

Was this helpful?
Yes
No

archivePlan( )

Archives a single plan.

The archivePlan() function returns a Promise that resolves to the newly-archived plan.

When a plan is archived, the plan

  • Is no longer available for display or selection by visitors. This is because the plan's public property is automatically set to false.
  • Cannot be purchased.
  • Cannot be "un-archived", meaning the plan cannot be made active again.

Plan archiving does not impact existing purchases made for the plan. All purchases for the plan are still active and keep their payment options and terms.

Site owners can see archived plans in the Dashboard under Pricing Plans -> Archived Plans.

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
_idstringRequired
ID of the active plan to archive.
Response Object
ArchivePlanResponse
Was this helpful?
Yes
No

arrangePlans( )

Changes the display order of the pricing plans on the site page and in the Dashboard.

The arrangePlans() function returns a Promise that resolves when the plans are rearranged on the site page and in the Dashboard.

To rearrange the order of the plans, provide a list of the IDs for all non-archived plans in the desired order, including hidden plans.

Note: Make sure to provide all non-archived plan IDs to avoid unpredictable results.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
idsArray<string>Required
IDs of all non-archived plans in the order you want them arranged.
Response Object
void
Was this helpful?
Yes
No

clearPrimary( )

Sets all pricing plans to no longer be primary.

The clearPrimary() function returns a Promise that is resolved when there are no pricing plans marked as primary.

After clearing the primary plan, when viewing pricing plans on the site, no plan is highlighted with a customizable ribbon.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Request
This method does not take any parameters
Response Object
void
Was this helpful?
Yes
No

createPlan( )

Creates a pricing plan.

The createPlan() function returns a Promise that resolves to a newly-created pricing plan after is has successfully been created.

The passed plan object must contain a pricing model. A pricing model can be one of the following:

  • A subscription: A subscription with recurring payment and how often the plan occurs. Subscriptions can have free trial days.
  • A plan that does not 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 created by this function are available to the site owner in the Pricing Plans section in the Dashboard.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
planPlanRequired
Information for the plan being created.
Response Object
Plan
Was this helpful?
Yes
No

getPlan( )

Retrieves a pricing plan by the specified ID.

The getPlan() function returns a Promise that resolves to a plan whose ID matched the specified ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Pricing Plans
Learn more about permission scopes.
Params
_idstringRequired
Plan ID.
Response Object
Plan
Was this helpful?
Yes
No

getPlanStats( )

Retrieves statistics about the pricing plans.

The getPlanStats() function returns a Promise that resolves to statistics about the plan on the site.

Currently this function provides only the total number of pricing plans, including archived plans.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Pricing Plans
Learn more about permission scopes.
Request
This method does not take any parameters
Response Object
GetPlanStatsResponse
Was this helpful?
Yes
No

listPlans( )

Retrieves a list of pricing plans.

The listPlans() function returns a Promise that resolves to a list of up to 100 pricing plans. This includes public, hidden, and archived plans.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Pricing Plans
Learn more about permission scopes.
Params
optionsListPlansOptions
Options for filtering and paging the list of plans.
Response Object
ListPlansResponse
Was this helpful?
Yes
No

listPublicPlans( )

Retrieves a list of public pricing plans.

The listPublicPlans() function returns a Promise that resolves to a list of up to 100 public pricing plans. Public plans are visible plans that site visitors can see on the site and purchase.

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Orders
Read Pricing Plans
Learn more about permission scopes.
Params
optionsListPublicPlansOptions
Options for filtering and paging the list of public plans.
Response Object
ListPublicPlansResponse
Was this helpful?
Yes
No

makePlanPrimary( )

Marks a pricing plan as the primary pricing plan.

The makePlanPrimary() function returns a Promise that resolves to the now primary pricing plan.

Only a single plan can be marked as a primary plan at any given time. If there is an existing plan marked as primary, calling makePlanPrimary() causes the existing primary plan to lose its primary status.

When viewing pricing plans on the site, the primary plan is highlighted with a customizable ribbon.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
_idstringRequired
ID of the pricing plan to set as the primary plan.
Response Object
MakePlanPrimaryResponse
Was this helpful?
Yes
No

queryPublicPlans( )

Creates a query to retrieve a list of public pricing plans.

The queryPublicPlans() function builds a query to retrieve a list of up to 1,000 public plans and returns a PublicPlansQueryBuilder object.

The returned object contains the query definition which is typically used to run the query using the find() function.

You can refine the query by chaining PublicPlansQueryBuilder functions onto the query. PublicPlansQueryBuilder functions enable you to sort, filter, and control the results that queryPublicPlans() returns.

queryPublicPlans() runs with the following PublicPlansQueryBuilder defaults that you can override:

The functions that are chained to queryPublicPlans() are applied in the order they are called. For example, if you sort on the _createdDate property in ascending order and then on the _id property in ascending order, the results are sorted first by the created date of the items and then, if there are multiple results with the same date, the items are sorted by _id in ascending order, per created date value.

The following PublicPlansQueryBuilder functions are supported for the queryPublicPlans() function. For a full description of the Plans object, see the object returned for the items property in PublicPlansQueryResult.

PROPERTYSUPPORTED FILTERS & SORTING
_ideq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()
primaryeq(),ne(),exists(),in(),hasSome(),ascending(),descending()
_createdDateeq(),ne(),exists(),in(),hasSome(),gt(),lt(),ascending(),descending()
_updatedDateeq(),ne(),exists(),in(),hasSome(),gt(),lt(),ascending(),descending()
slugeq(),ne(),exists(),in(),hasSome(),startsWith(),ascending(),descending()

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Orders
Read Pricing Plans
Learn more about permission scopes.
Request
This method does not take any parameters
Response Object
PlansQueryBuilder
Was this helpful?
Yes
No

setPlanVisibility( )

Sets visibility for non-archived pricing plans.

The setPlanVisibility() functions returns a Promise that resolves to a pricing plan when its visibility has successfully been set.

By default, pricing plans are public, meaning they are visible. Plans can be hidden so that site members and visitors cannot see or choose them.

As opposed to archiving, setting visibility can be reversed. This means that a public plan can be hidden, and a hidden plan can be made public (visible).

Note: An archived plan always remains archived and cannot be made active again. When archiving a plan, its public property is automatically set to false so that it is hidden.

Changing a plan's visibility does not impact existing orders for the plan. All orders for hidden plans are still active and keep their terms and payment options.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
_idstringRequired
The ID of the plan to either display or hide on the site page.

visiblebooleanRequired
Whether to set the plan as visible.
Response Object
SetPlanVisibilityResponse
Was this helpful?
Yes
No

updatePlan( )

Updates a pricing plan.

The updatePlan() function returns a Promise that resolves to an updated plan.

Updating a plan does not impact existing purchases made for the plan. All purchases keep the details of the original plan that was active at the time of the purchase.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Pricing Plans
Learn more about permission scopes.
Params
_idstringRequired
ID of the plan to update.

planUpdatePlanRequired
Response Object
Plan
Was this helpful?
Yes
No