CorvidReference

wix-paid-plans

The wix-paid-plans module contains functionality for working with paid plans from client-side code.

Using the Paid Plans API, you can build a customized membership plan experience.

First, set up your site to:

When plans are set up, you can use the API to:

  • Get information about paid plans.
  • Let site visitors purchase a plan directly, as if they were using the Paid Plans app.
  • Let site visitors purchase a plan using your own customized process.

There are two flows for setting up paid plans: Direct purchases and customized purchases.

Direct purchasing is the same as when purchasing a plan with the Paid Plans app. Everything is handled, from requesting the plan, through paying for the plan. If you need standard paid plan processing, call the purchasePlan() function.

The following outlines the steps in a direct-purchase lifecycle:

  1. Get a list of membership plans from one of:
    • A dataset connected to the Plans collection.
    • A query on the Plans collection.
  2. A logged-in site visitor selects a membership plan by clicking the plan or a button. (If the visitor is not logged-in, the sign up page is displayed.)
  3. The corresponding event handler calls a function to handle all stages of buying the plan (ordering, purchasing, and payment):
    • If the plan is free, the plan is immediately ordered and is considered purchased (transaction status is "Paid").
    • If the plan is not free, the plan is ordered but not yet purchased (transaction status is "Pending"). The site visitor fills in contact details and selects a payment method (transaction status is now "Paid").
  4. Handle additional updates when a plan is successfully purchased using the onPlanPurchased() event.*

Let site visitors order a plan for future purchase (such as after a visitor enters payment information). You customize the entire process of selecting, requesting, and paying for a plan. You can add elements, such as confirmation lightboxes and forms, to customize the visitor experience.

To let the visitor request a plan, call the orderPlan() function.

The following outlines the steps for customizing the paid plan purchase:

  1. Get a list of membership plans from one of:
    • A dataset connected to the Plans collection.
    • A query on the Plans collection.
  2. A logged-in site visitor selects a membership plan by clicking the plan or a button. (If the visitor is not logged-in, the sign up page is displayed.)
  3. The corresponding event handler calls the orderPlan() function to handle the initial order of the plan.
  4. The site visitor uses a series of customized elements, such as lightboxes, and forms.
  5. The site visitor uses the Wix Pay payment method to complete the purchase.
  6. Handle additional updates when a plan is successfully purchased using the onPlanPurchased() event.*

To use the Paid Plans API, import wixPaidPlans from the wix-paid-plans module:

   import wixPaidPlans from 'wix-paid-plans';

Note

To work with the Paid Plans API, you need to publish your site.

Table of Contents

OBJECTS

?
Objects used when setting, getting, or calling the properties and methods listed above.
OrderResultAn object representing an order result.
OrderResultBodyAn object representing IDs of an order result.
PurchaseResultAn object representing a purchase result for a non-free plan.
PurchaseResultFreeAn object representing a purchase result for a free plan.

Related Content

    FAQ

      orderPlan( )

      Orders a paid plan.

      Description

      To process paid plans on your site, first set up your site to offer paid plans as described in About Paid Plans. When setting up your site to accept paid plans, define the plans you want to offer.

      The orderPlan() function returns a Promise that resolves to an OrderResult object when the visitor completes the order process. Use this result only for display purposes.

      Ordering a plan places an order for the plan, without actually purchasing it. You can then continue the payment process with the Wix Pay payment method, which applies the plan to the visitor on completion of payment.

      To understand how orderPlan() is used in a customized paid plan lifecycle, see Customized Paid Plan Purchases.

      Note

      To work with the Paid Plans API, you need to publish your site.

      Syntax

      function orderPlan(planId: string): Promise<OrderResult>
      PARAMETERS
      ?
      Values that you pass to a function.
      planId
      string
      The plan ID.
      RETURN VALUE
      ?
      Value that a function evaluates to when it is finished running.
      Promise<OrderResult>
      Fulfilled - The created order.

      Examples

      Order a paid plan

      import wixPaidPlans from 'wix-paid-plans';
      
      let planId = // Get the plan ID
      
      export function myOrderButton_click(event) {
        wixPaidPlans.orderPlan(planId)
          .then( (myOrder) => {
              let myOrderId = myOrder.orderId;
              let myWixPayOrderId = myOrder.wixPayOrderId;
              let myStatus = myOrder.status;
          } );
        }
      
      
      /* myOrder:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "status": 200
       * }
       */

      A full order plan scenario

      This example demonstrates a customized paid plans scenario. The customized elements include:

      • An intermediary page that displays all plans before ordering
      • A lightbox

      In the interest of simplicity the code does not deal with display considerations or validations that would normally be required to make sure users perform the flow as intended.

      The code assumes two pages:

      • The plan viewer page lists the plans and lets the visitor pick one.

      • A dynamic page shows one plan's details and lets the visitor order the plan.

      The plan viewer page has the following elements:

      • planDataset: Connects the page to the Plans collection.
      • planRepeater: Displays fields for each plan.
      • viewButton: Displays the ordering page for the selected plan.

      The dynamic page has the following elements:

      • dynanicDataset: Connects the page to the Plans collection.
      • planName: Text element that displays the plan's name.
      • planDescription: Text element that displays the plan's tagline.
      • orderPlanButton: Performs a request to order the plan.
      • orderCreated: A customized lighbox. The lightbox could, for example, display plan details and ask for additional confirmation.
      /****************************************
      * Code on a plan viewer page
      *****************************************/
      // For navigating to a dynamic page:
      import wixLocation from 'wix-location';
      // If the site visitor clicks a plan's button,
      // the browser relocates to that plan's dynamic page,
      // with more details.
      $w.onReady(function () {
         $w("#viewButton").onClick( (event, $w) => {
            let slug = $w("#planDataset").getCurrentItem().slug;
      
            // We customized the URL to the plan's dynamic
            // page when we created it. 
            wixLocation.to('/my-plans/'+ slug)
        }));
      });
      
      
      /****************************************
      * Code on a plan ordering dynamic page
      *****************************************/
      // For a lightbox:
      import wixWindow from 'wix-window';
      // For Wix Pay, but any payment method is OK:
      import wixPay from 'wix-pay';
      // For paid plans
      import paidPlans from 'wix-paid-plans';
      
      
      $w.onReady(function () {
      
         // When the collection is accessible...
         $w('#dynamicDataset').onReady( () => {
      
         // Assign the currently-selected plan to currentPlanObject
         const currentPlanObject = $w("#dynamicDataset").getCurrentItem();
      
         // Display details about the current plan
         $w('#planName').text = currentPlanObject.name;
         $w('#planDescription').text = currentPlanObject.description;
      
         // Assign the currently-selected plan's ID to planId. This
         // unique identifier will be used for ordering the plan.
         const planId = currentPlanObject._id;
      
      
         // Order the plan by button click
         $w("orderPlanButton").onClick( (event) => {
      
         // Provide the plan's ID to the
         // orderPlan() function. The function returns
         // an object containing the plan's properties.
         const order = paidPlans.orderPlan(planId).then(ord => {
      
         const planWithOrder = {
           plan: currentPlanObject,
           order: ord
         };
      
         // Use a customized lightbox to continue processing the order.
         wixWindow.openLightbox("orderCreated", planWithOrder)
           .then( (data) => {
           const receivedData = data;
         });
      
         });
        });
       });
      });
      

      purchasePlan( )

      Orders and purchases a paid plan.

      Description

      To process paid plans on your site, first set up your site to offer paid plans as described in About Paid Plans. When setting up your site to accept paid plans, define the plans you want to offer, including the payment method.

      The purchasePlan() function returns a Promise that resolves to either a PurchaseResult object when the visitor completes the purchase process for a non-free plan, or a PurchaseResultFree object when the visitor completes the purchase process for a free plan. Use this result only for display purposes.

      Purchasing a plan validates the plan, orders the plan, and continues the payment process with the Wix Pay API. After payment is complete, the plan is assigned to the visitor.

      To understand the lifecycle of how purchasePlan() is used, see Direct Purchase of a Paid Plan.

      Note

      To work with the Paid Plans API, you need to publish your site.

      Syntax

      function purchasePlan(planId: string): Promise<PurchaseResult>
      PARAMETERS
      ?
      Values that you pass to a function.
      planId
      string
      The plan ID.
      RETURN VALUE
      ?
      Value that a function evaluates to when it is finished running.
      Fulfilled - The created purchase.

      Examples

      Purchase a non-free plan on button click

      import wixPaidPlans from 'wix-paid-plans';
      import wixPay from 'wix-paid-plans';
      
      let planId = // Get the plan ID for a non-free plan
      
      export function myPurchaseButton_click(event) {
        wixPaidPlans.purchasePlan(planId)
          .then( (myPurchase) => {
              let myOrderId = myPurchase.orderId;
              let myWixPayOrderId = myPurchase.wixPayOrderId;
              let myStatus = myPurchase.status;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "status": 200
       * }
       */

      Purchase a free plan on button click

      import wixPaidPlans from 'wix-paid-plans';
      import wixPay from 'wix-paid-plans';
      
      let planId = // Get the plan ID for a free plan
      
      export function myPurchaseButton_click(event) {
        wixPaidPlans.purchasePlan(planId)
          .then( (myPurchase) => {
              let myOrderId = myPurchase.orderId;
              let myStatus = myPurchase.status;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "status": 200
       * }
       */

      OrderResult

      An object representing an order result.

      See Also

      orderPlan( )

      Syntax

      type OrderResult = {
        status: string
        orderId: string
        wixPayOrderId: string
      }
      MEMBERS
      ?
      The properties of an object.
      status
      string
      Status of the order, such as 200 if the order succeeded.
      orderId
      string
      ID of the order.
      wixPayOrderId
      string
      Wix Pay ID of the order being purchased.

      Examples

      Order a paid plan

      import wixPaidPlans from 'wix-paid-plans';
      
      let planId = // Get the plan ID
      
      export function myOrderButton_click(event) {
        wixPaidPlans.orderPlan(planId)
          .then( (myOrder) => {
              let myOrderId = myOrder.orderId;
              let myWixPayOrderId = myOrder.wixPayOrderId;
              let myStatus = myOrder.status;
          } );
        }
      
      
      /* myOrder:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "status": 200
       * }
       */

      OrderResultBody

      An object representing IDs of an order result.

      See Also

      orderPlan( )

      Syntax

      type OrderResultBody = {
        cashierOrderId: string
        orderId: string
        wixPayOrderId: string
      }
      MEMBERS
      ?
      The properties of an object.
      cashierOrderId
      string
      ID of the cashier order.
      orderId
      string
      ID of the order.
      wixPayOrderId
      string
      ID of the Wix Pay order.

      Examples

      Order a paid plan

      import wixPaidPlans from 'wix-data';
      
      let planId = // Get the plan ID
      
      export function myOrderButton_click(event) {
        wixPaidPlans.orderPlan(planId)
          .then( (myOrder) => {
              let  myCashierOrderId = myOrder.body.cashierOrderId;
              let  myOrderId = myOrder.body.orderId;
              let  myStatus = myOrder.status;
          } );
        }
      
      
      /* myOrder:
       * {
       *  "body":
       *    "CashierOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\"
       *    "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *    "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "status": 200
       * }
       */

      PurchaseResult

      An object representing a purchase result for a non-free plan.

      See Also

      purchasePlan( )

      Syntax

      type PurchaseResult = {
        status: string
        orderId: string
        wixPayOrderId: string
      }
      MEMBERS
      ?
      The properties of an object.
      status
      string
      Status of the purchase, such as 200 if the purchase succeeded.
      orderId
      string
      ID of the order being purchased.
      wixPayOrderId
      string
      Wix Pay ID of the order being purchased. Returned for non-free plans.

      Examples

      Purchase a non-free plan

      import wixPaidPlans from 'wix-paid-plans';
      import wixPay from 'wix-paid-plans';
      
      let planId = // Get the plan ID for a non-free plan
      
      export function myPurchaseButton_click(event) {
        wixPaidPlans.purchasePlan(planId)
          .then( (myPurchase) => {
              let myOrderId = myPurchase.orderId;
              let myWixPayOrderId = myPurchase.wixPayOrderId;
              let myStatus = myPurchase.status;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "status": 200
       * }
       */

      PurchaseResultFree

      An object representing a purchase result for a free plan.

      See Also

      purchasePlan( )

      Syntax

      type PurchaseResultFree = {
        orderId: string
        status: string
      }
      MEMBERS
      ?
      The properties of an object.
      orderId
      string
      ID of the order being purchased.
      status
      string
      Status of the purchase, such as 200 if the purchase succeeded.

      Examples

      Purchase a free plan

      import wixPaidPlans from 'wix-paid-plans';
      import wixPay from 'wix-paid-plans';
      
      let planId = // Get the plan ID for a free plan
      
      export function myPurchaseButton_click(event) {
        wixPaidPlans.purchasePlan(planId)
          .then( (myPurchase) => {
              let myOrderId = myPurchase.orderId;
              let myStatus = myPurchase.status;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "status": 200
       * }
       */