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.
  • Let site visitors cancel plan subscriptions (orders) that they have purchased.

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.
PurchaseResultAn object representing a purchase result for a non-free plan.
PurchaseResultFreeAn object representing a purchase result for a free plan.

Related Content

    FAQ

      cancelOrder( )

      Cancels a specific order (subscription) of a plan.

      Description

      The cancelOrder() function cancels an order (subscription) of a plan, after verifying that the site member is logged in.

      Keep in mind that a site member can order several subscriptions of the same plan. This API does not cancel the plan and remove all corresponding subscriptions. This API removes only the one order (subscription) of the plan.

      Note

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

      Syntax

      function cancelOrder(orderId: string): Promise<void>
      PARAMETERS
      ?
      Values that you pass to a function.
      orderId
      string
      The plan subscription's order ID.
      RETURN VALUE
      ?
      Value that a function evaluates to when it is finished running.
      Promise<void>

      Fulfilled - When the subscription is cancelled. Rejected - Error message.

      Examples

      Cancel an order (subscription) on button click

      import wixPaidPlans from 'wix-paid-plans'; 
      import wixWindow from 'wix-window';        
      
      const orderId = // Get the order ID of the subscription to cancel
      
      // Call cancelOrder() when user clicks button
      export function cancelButton_click(event) {  
      
        wixPaidPlans.cancelOrder(orderId) 
      
          // Additional processing based on cancellation results
          .then ( () => {
             wixWindow.openLightbox("orderCanceled")
            } )
           .catch( (err) => {
             wixWindow.openLightbox("cancelFailed")
           } );
        }

      A full cancel order (subscription) scenario

      This example demonstrates a full scenario for cancelling a paid plan order (subscription).

      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.

      Customized elements include:

      • A Subscriptions collection. This collection contains all plan orders (subscriptions) purchased by the site member and each subscription's status.
      • A cancelButton button that the site member clicks to cancel an order (subscription) of a plan.
      • A subscriptionDataset dataset that connects the page to the Subscriptions collection.
      • Two lightboxes, orderCanceled and cancelFailed that notify the site member if a subscription is cancelled.
      import wixPaidPlans from 'wix-paid-plans';  
      import wixData from 'wix-data';             
      import wixUsers from 'wix-users';           
      import wixWindow from 'wix-window';         
      
      $w.onReady(function () {
        $w('#subscriptionDataset').onReady( () => {
      
           // Get the order ID for the subscription to cancel
           const subscription = $w("#subscriptionDataset").getCurrentItem();   
           const orderId = subscription.orderId; 
      
           $w("cancelButton").onClick( (event) => {
      
             // Cancel the specific subscription of the plan 
             wixPaidPlans.cancelOrder(orderId)
              .then( () => {
      
              // Let user know that cancellation succeeded
              wixWindow.openLightbox("orderCanceled");
      
              // Get details for updating status of existing subscription
              const user = wixUsers.currentUser;   
      	      const toUpdate = {
      		 	  "_id":         subscription._id,
      		 	  "planName":    subscription.planName,
      		 	  "planId":      subscription.planId,
      		 	  "orderId":     subscription.orderId,
                    "memberId":    user.id,
                    "dateCreated": subscription.dateCreated,
                    "canceled":    true,            // Set cancellation to true
                    "dateUpdated": Date().toString()		
                };
          
                // Update subscription in collection to show the subscription is canceled
                wixData.update("Subscriptions", toUpdate)
      
      	     // Let user know if cancellation failed
        	     .catch((err) => {
      	        wixWindow.openLightbox("cancelFailed");
      	      });
      	   })
      	})
        })
      })
      
      

      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. Rejected - Error message.

      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;
          } );
        }
      
      
      /* myOrder:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\"
       * }
       */

      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 2 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 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 myWixPayStatus = myPurchase.wixPayStatus;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "wixPayStatus": \"Successful"
       * }
       */

      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;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\"
       * }
       */

      OrderResult

      An object representing an order result.

      See Also

      orderPlan( )

      Syntax

      type OrderResult = {
        orderId: string
        wixPayOrderId: string
      }
      MEMBERS
      ?
      The properties of an object.
      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;
          } );
        }
      
      
      /* myOrder:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\"
       * }
       */

      PurchaseResult

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

      See Also

      purchasePlan( )

      Syntax

      type PurchaseResult = {
        orderId: string
        wixPayOrderId: string
        wixPayStatus: string
      }
      MEMBERS
      ?
      The properties of an object.
      orderId
      string
      ID of the order being purchased.
      wixPayOrderId
      string
      Wix Pay ID of the order being purchased. Returned for non-free plans.
      wixPayStatus
      string

      Payment status in Wix Pay. One of:

      • "Successful": Payment was successfully received.
      • "Pending": Payment is pending payment provider approval.
      • "Failed": Payment has failed.
      • "Chargeback": Payment is chargeback.
      • "Refunded": Payment was fully refunded.
      • "Offline": Payment will be executed offline.
      • "PartiallyRefunded": Payment was partially refunded.
      • "Cancelled": Payment was cancelled and was not processed.
      • "Undefined": Payment status is pending payment provider input.

      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 myWixPayStatus = myPurchase.wixPayStatus;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\",
       *  "wixPayOrderId": \"06af8fd6-6c82-4b51-bc08-0b556aad6f4f\",
       *  "wixPayStatus": \"Successful"
       * }
       */

      PurchaseResultFree

      An object representing a purchase result for a free plan.

      See Also

      purchasePlan( )

      Syntax

      type PurchaseResultFree = {
        orderId: string
      }
      MEMBERS
      ?
      The properties of an object.
      orderId
      string
      ID of the order being purchased.

      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;
          } );
        }
      
      
      /* myPurchase:
       * {
       *  "orderId": \"b3fb3a4d-c223-4040-8bc3-8dfdefb1bafc\"
       * }
       */