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.
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 periods after which the plan starts billing the buyer automatically.
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.
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.
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.
You can assign tags to plans to classify them and filter by them later. Tags are managed by the Tags API, 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 assigns and unassigns tags on up to 100 plans by ID, and returns the result for each plan.
- 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 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.
Every tag change emits two events. Plan Updated fires with the plan's new state, and 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.
It's important to note the following points before starting to code:
- The Wix user must install the Wix 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.
- To sell plans, a Wix user must connect a payment provider on the site.
- In this API, perks act as a list for marketing purposes. To create actual benefits, see Benefit Programs.
- 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.
- 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.