> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt ## Resource: wix-pricing-plans-backend ## Article: Introduction ## Article Link: https://dev.wix.com/docs/velo/apis/wix-pricing-plans-backend/introduction.md ## Article Content: # Introduction Use the Pricing 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 the Pricing Plan APIs. ### Set up pricing plans To use Pricing Plans APIs to manage your plans, first set up your site to: + Accept payments as described in [About Accepting Payments](https://support.wix.com/en/article/about-accepting-payments). + Offer membership plans as described in [About Pricing Plans](https://support.wix.com/en/article/about-pricing-plans). When setting up your site to accept pricing plans, define the plans you want to offer [using the Dashboard](https://support.wix.com/en/article/creating-a-plan-in-pricing-plans) or [using the Pricing Plan APIs](wix-pricing-plans-backend/create-plan). ### Manage pricing plans You can use the Pricing Plans API to create and manage plans. You can: + Create and update pricing plans. + List and query pricing plans. + Set which plans are public and which plans are hidden. + Archive plans. + Set or clear the primary plan. This determines if a plan is highlighted with a custom ribbon when viewing the plans on the site. + Get statistics about the plans. + Rearrange the order of how plans display. ### Ordering pricing plans With the Pricing Plan APIs you can customize the purchase flow. For example, you may add your own popups and forms. When creating or updating a plan, you can set if a plan can be ordered by a given site member only once or multiple times using the `maxPurchasesPerBuyer` property. Updating the properties of a pricing plan does not affect any current orders of the plan by site members. The existing orders retain their existing terms and pricing. Members can purchase pricing plans in 2 ways: + **Online**. Members order and pay for their plans on your site without manual intervention. + **Offline**. Members place their order by phone, text, or email. You manually record each stage of the transaction. You can use the Pricing Plans APIs to manage the purchase of both online and offline orders. ![Ordering Flow](https://wixmp-833713b177cebf373f611808.wixmp.com/images/velo-images/media_ordering.png) #### A typical online ordering flow 1. Use the Pricing Plans [`createPlan()`](wix-pricing-plans-backend/create-plan) function to create the plans you want to offer on your site. 1. A site visitor chooses a plan for purchase. 1. Use the Checkout [`previewPrice()`](wix-pricing-plans-backend/checkout/preview-price) function to show the site visitor a preview of how much the plan will cost, including or excluding taxes, as defined on your site. 1. If the site visitor confirms, ask the visitor to log in. 1. Use the Checkout [`previewOnlineOrder()`](wix-pricing-plans-backend/checkout/preview-online-order) function to get final confirmation. 1. After receiving confirmation, call the [`createOnlineOrder()`](wix-pricing-plans-backend/checkout/create-online-order) function to start a draft of the order. `createOnlineOrder()` returns a `wixPayOrderId`. 1. Direct the order to Wix Pay's [`startPayment()`](wix-pay-frontend/start-payment) function, sending the `wixPayOrderId` as an input parameter. 1. After payment is made, the functionality available with the Orders APIs is available for managing the orders. #### A typical offline ordering flow 1. Use the Pricing Plans [`createPlan()`](wix-pricing-plans-backend/createPlan) function to create the plans you want to offer on your site. 1. A site visitor contacts you offline to make a purchase. 1. Use the Checkout [`previewPrice()`](wix-pricing-plans-backend/checkout/preview-price) and the [`previewOfflineOrder()`](wix-pricing-plans-backend/checkout/preview-offline-order) functions to send the buyer the order details for confirmation. 1. Call the [`createOfflineOrder()`](wix-pricing-plans-backend/checkout/create-offline-order) function to start a draft of the order. 1. Receive payment. 1. After payment is made, call the Orders [`markAsPaid()`](wix-pricing-plans-backend/orders/mark-as-paid) function. 1. The functionality available with the Orders APIs is available for managing the orders. ### Roles and permissions You need "Manage Pricing Plans" [permissions](https://support.wix.com/en/article/roles-permissions-accessing-roles-permissions) to perform management functions, such as [`createPlan()`](wix-pricing-plans-backend/createPlan), [`update-plan()`](wix-pricing-plans-backend/update-plan), [`archivePlan()`](wix-pricing-plans-backend/archive-plan), and so on. The following roles are predefined with "Manage Pricing Plans" permissions when the Pricing Plan app is added to the site: + [Owner](https://support.wix.com/en/article/roles-permissions-overview#owner1072) + [Admin (Co-Owner)](https://support.wix.com/en/article/roles-permissions-overview#admin-co-owner) + [Website Manager](https://support.wix.com/en/article/roles-permissions-overview#website-manager) + [Website Designer](https://support.wix.com/en/article/roles-permissions-overview#website-designer) + [Back Office Manager](https://support.wix.com/en/article/roles-permissions-overview#back-office-manager953) You do not need "Manage Pricing Plans" permissions to use the [`listPublicPlans()`](wix-pricing-plans-backend/listPublicPlans) and [`queryPublicPlans()`](wix-pricing-plans-backend/queryPublicPlans) functions. ### Pricing models Pricing models contain the [pricing and duration options](https://support.wix.com/en/article/pricing-plans-creating-a-plan#step-3-setting-the-price-and-duration-of-your-plan) for a plan. Plans are based on a pricing model, which is defined with the plan's `pricing` property. A pricing model can be one of the following: + **A subscription:** A plan with recurring payment cycles. *Example:* A 1-year subscription with monthly, recurring payments. Each payment is $25, so the total price for the plan is $300. In this example, the subscription is in its third month. `cycleDuration` is the length of one payment cycle. Multiply `cycleDuration`'s `count` by `cycleCount` to get the subscription duration. Currently, `cycleDuration` only supports a value of `1`. `index` of `currentCycle` is the current payment cycle for the subscription. `index` is `0` when the order is in a free trial period. In all other cases, the `index` starts with `1` for the first payment cycle in the subscription. For orders with a single payment, the `index` will remain `1` throughout the duration. ```javascript "pricing": { "subscription": { "cycleDuration": { // Payment recurs every month "count": 1, "unit": "MONTH" }, // for 12 times "cycleCount": 12 }, "prices": [{ "duration": { "cycleFrom": 1, "numberOfCycles": 12 }, "price": { "subtotal": "25", "discount": "0", "total": "25", "currency": "USD" } }] }, ... "currentCycle": { "index": 3, "startedDate": "2022-03-01T13:45:53.129Z", "endedDate": "2022-04-01T13:45:53.129Z" }, ``` + **A plan that does not renew:** A plan paid for with a single payment. The plan does not renew after the duration. *Example:* A plan with a single payment of $35 for 3 months. The `duration` `cycleFrom` and `numberOfCycles` will both be `1`, as the single price applies to the entirety of the subscription. `index` of `currentCycle` will remain `1` throughout the duration. ```javascript "pricing": { "singlePaymentForDuration": { // Plan duration is 3 months "count": 3, "unit": "MONTH" }, "prices": [{ "duration": { "cycleFrom": 1, "numberOfCycles": 1 }, "price": { "subtotal": "35", "discount": "0", "total": "35", "currency": "USD" } }] }, ... "currentCycle": { "index": 1, "startedDate": "2022-01-01T13:45:53.129Z", "endedDate": "2022-04-01T13:45:53.129Z" }, ``` + **An unlimited plan:** A plan paid for with a single payment. The plan does not expire and remains valid until canceled. *Example:* An unlimited plan that is paid for in advance with one payment of $200. `singlePaymentUnlimited` is `true`. The `duration` `cycleFrom` and `numberOfCycles` will remain `1` throughout the duration of the plan. `index` of `currentCycle` will remain `1` throughout the duration. `singlePaymentUnlimitedPlans` don't return an `endedDate` in `currentCycle`. ```javascript "pricing": { "singlePaymentUnlimited": true, "prices": [{ "duration": { "cycleFrom": 1, "numberOfCycles": 1 }, "price": { "subtotal": "200", "discount": "0", "total": "200", "currency": "USD" } }] }, ... "currentCycle": { "index": 1, "startedDate": "2021-06-015T13:45:53.129Z" }, ``` ### Free plans and free trial periods A free plan that is valid until canceled is a `singlePaymentUnlimited` pricing model. A free plan with a limited duration is treated as a `singlePaymentForDuration` pricing model. A site owner can also add a free trial period, in days, to a `subscription` pricing model. When the free trial is over, the first payment cycle begins and the buyer is billed. During the free trial period, the `index` of `currentCycle` is `0`. A buyer only receives the free trial period for the first time they purchase a plan. For example, a buyer purchases a monthly plan for 3 months that includes a 7-day free trial period. The buyer may purchase the same plan again, for another 3 months, but will not receive the 7-day free trial period. When a buyer cancels their order during the free trial period, their subscription will expire at the end of the free trial period and they will not be billed. A site owner can [cancel an ordered plan](wix-pricing-plans-backend/orders/cancel-order) during the free trial period and choose to apply the cancellation `IMMEDIATELY` or at the `NEXT_PAYMENT_DATE`. Canceling `IMMEDIATELY` ends the subscription for the buyer immediately, even during the free trial period, and the buyer won't be billed. Canceling at the `NEXT_PAYMENT_DATE` allows the buyer to continue using the benefits of the subscription until the end of the free trial period. Then, the subscription ends and the buyer is not billed. ### Pricing plan types and visibility + **Public pricing plans** are visible plans that site members and visitors can see on the site and purchase. By default, pricing plans are public when created. + **Hidden pricing plans** are plans whose `public` property has been set to `false`. These plans cannot be seen on the site by the site member or visitor. For example, consider hiding a plan if it has reached its maximum capacity and temporarily is not available for purchase. Changing a plan’s visibility with the `public` property does not impact existing purchases. All purchases for hidden plans are still active and keep their terms and payment options. + **Active pricing plans** include all non-archived plans, such as public plans and hidden plans. + **Archived pricing plans** are plans that are no longer needed on the site. For example, discontinued plans. When a plan is archived, it is no longer visible as a public plan that can be chosen by site visitors. The `public` property is automatically set to `false` when a plan is archived. Archived plans cannot be purchased. Site owners can see archived plans in the Dashboard under **Pricing Plans -> Archived Plans**. Archiving cannot be reversed. Once archived, a plan cannot be set as active again for purchase. Archiving does not impact existing purchases made for the plan. All purchases are still active and keep their pricing and terms. ### Importing pricing plans To use the Pricing Plans API, import `wixPricingPlansBackend` from the `wix-pricing-plans-backend` module. ```javascript import wixPricingPlansBackend from 'wix-pricing-plans-backend'; ```