startOnlinePurchase( )

Orders and purchases a pricing plan.

Description

The startOnlinePurchase() function returns a Promise that resolves to a Purchase object when the member completes the purchase process. Depending on whether the plan is free, the Purchase object returns different properties.

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

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 member.

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

Notes:
The pricing plan startOnlinePurchase() function replaces the deprecated paid plans purchasePlan() function. The deprecated function will continue to work, but will not receive updates. To keep any existing code compatible with future changes, see the purchasePlan() migration instructions.
To work with the Pricing Plans API, you need to publish your site.

Syntax

function startOnlinePurchase(planId: string, [startDate: Date]): Promise<Purchase>

startOnlinePurchase Parameters

NAME

TYPE

DESCRIPTION

planId

string

The plan ID.

startDate

Optional

Date

Start date and time for the ordered plan.

Returns

Fulfilled - Details about the purchased plan.

Return Type:

Promise<Purchase>

NAME

TYPE

DESCRIPTION

order

Order

The order being purchased.

wixPayStatus

string

Payment status in Wix Pay. Omitted for free plans. 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.

Was this helpful?

Purchase a non-free plan on button click

Copy Code

1import { checkout } from 'wix-pricing-plans-frontend';
2
3// Sample planId value: '099e2c86-3b7e-4477-8c27-f77402b8cced'
4
5$w('#myOrderButton').onClick((event) => {
6    checkout.startOnlinePurchase(planId)
7    .then((purchasedOrder) => {
8      const myOrderId = purchasedOrder.order._id;
9      const myWixPayOrderId = purchasedOrder.order.wixPayOrderId;
10      const myWixPayStatus = purchasedOrder.wixPayOrderStatus   
11
12      console.log('Success! Created order:', purchasedOrder);
13      return purchasedOrder;
14    })
15    .catch((error) => {
16        console.error(error);
17    })
18});
19
20/* myPurchase object after payment processed
21 * {
22 *   "_id": "89dcd5fd-8c6b-4b76-93b7-ee7160366583",
23 *   "planId": "099e2c86-3b7e-4477-8c27-f77402b8cceb",
24 *   "subscriptionId": "18926aae-b6d0-4487-a8de-7e1b8dd97441",
25 *   "wixPayOrderId": "69fd8594-6b40-4fd8-9da4-9ea8cb5dff49",
26 *   "buyer": {
27 *     "memberId": "0c9bca47-1f00-4b92-af1c-7852452e949a",
28 *     "contactId": "0c9bca47-1f00-4b92-af1c-7852452e949a"
29 *   },
30 *   "priceDetails": {
31 *     "subtotal": "74.99",
32 *     "discount": "0",
33 *     "total": "74.99",
34 *     "planPrice": "74.99",
35 *     "currency": "EUR",
36 *     "subscription": {
37 *       "cycleDuration": {
38 *           "count": 1,
39 *           "unit": "MONTH"
40 *       },
41 *       "cycleCount": 3
42 *   }},
43 *   "pricing": {
44 *     "subscription": {
45 *       "cycleDuration": {
46 *           "count": 1,
47 *           "unit": "MONTH"
48 *       },
49 *       "cycleCount": 3
50 *     },
51 *     "prices": [
52 *       {
53 *         "duration": {
54 *           "cycleFrom": 1,
55 *           "numberOfCycles": 3
56 *         },
57 *         "price": {
58 *           "subtotal": "74.99",
59 *           "discount": "0",
60 *           "total": "74.99",
61 *           "currency": "EUR"
62 *         }
63 *       }
64 *     ]
65 *   },
66 *   "type": "ONLINE",
67 *   "orderMethod": "UNKNOWN",
68 *   "status": "DRAFT",
69 *   "autoRenewCanceled": false,
70 *   "lastPaymentStatus": "UNPAID",
71 *   "startDate": "2022-08-23T22:59:18.864Z",
72 *   "endDate": "2022-11-23T22:59:18.864Z",
73 *   "pausePeriods": [],
74 *   "earliestEndDate": "2022-11-23T22:59:18.864Z",
75 *   "currentCycle": {
76 *     "index": 1,
77 *     "startedDate": "2022-08-23T22:59:18.864Z",
78 *     "endedDate": "2022-09-23T22:59:18.864Z"
79 *   },
80 *   "planName": "Platinum Pro",
81 *   "planDescription": "",
82 *   "planPrice": "74.99",
83 *   "_createdDate": "2022-08-23T22:59:18.864Z",
84 *   "_updatedDate": "2022-08-23T22:59:18.864Z"
85 * }
86 */

Purchase a free plan that will start at a later date

Copy Code

1import wixPricingPlansFrontend from 'wix-pricing-plans-frontend';
2
3// Sample planId value: '099e2c86-3b7e-4477-8c27-f77402b8cced'
4//
5// Sample startDate value: new Date('2022-08-25T07:44:00.000Z')
6
7$w('#buyPlanButton').onClick((event) => {
8  wixPricingPlansFrontend.checkout.startOnlinePurchase(planId, startDate)
9  .then((freeOrder) => {
10      const myOrderId = freeOrder.order._id; 
11      const myOrderType = freeOrder.order.type;
12      console.log('Success! Created order:', freeOrder);
13      return freeOrder;          
14  })
15  .catch((error) => {
16    console.error(error);
17  })      
18});
19
20/* The object returns without wixPay properties,
21 * because no payment necessary.
22 * {
23 *   "_id": "d9667014-b773-40b1-871d-041cedd9302e",
24 *   "planId": "60f0e90f-06f6-4b9c-8cd7-5a02d015d98b",
25 *   "subscriptionId": "14e11d7d-46e2-46be-a8a0-5484f595701c",
26 *   "buyer": {
27 *     "memberId": "0c9bca47-1f00-4b92-af1c-7852452e949a",
28 *     "contactId": "0c9bca47-1f00-4b92-af1c-7852452e949a"
29 *   },
30 *   "priceDetails": {
31 *     "subtotal": "0",
32 *     "discount": "0",
33 *     "total": "0",
34 *     "planPrice": "0",
35 *     "currency": "EUR",
36 *     "singlePaymentForDuration": {
37 *       "count": 1,
38 *       "unit": "MONTH"
39 *     }
40 *   },
41 *   "pricing": {
42 *     "singlePaymentForDuration": {
43 *       "count": 1,
44 *       "unit": "MONTH"
45 *     },
46 *     "prices": [
47 *       {
48 *         "duration": {
49 *           "cycleFrom": 1,
50 *           "numberOfCycles": 1
51 *         },
52 *         "price": {
53 *           "subtotal": "0",
54 *           "discount": "0",
55 *           "total": "0",
56 *           "currency": "EUR"
57 *         }
58 *       }
59 *     ]
60 *   },
61 *   "type": "ONLINE",
62 *   "orderMethod": "UNKNOWN",
63 *   "status": "ACTIVE",
64 *   "lastPaymentStatus": "NOT_APPLICABLE",
65 *   "startDate": "2022-08-25T07:44:00.000Z",
66 *   "endDate": "2022-09-25T07:44:00.000Z",
67 *   "pausePeriods": [],
68 *   "earliestEndDate": "2022-09-25T07:44:00.000Z",
69 *   "planName": "Free Trial",
70 *   "planDescription": "Come try it out!",
71 *   "planPrice": "0",
72 *   "_createdDate": "2022-08-23T23:57:36.745Z",
73 *   "_updatedDate": "2022-08-23T23:57:36.745Z"
74 * }
75 */