applyCoupon( )

Applies a coupon to a draft order.

Description

The applyCoupon() function returns a Promise that resolves to an order with the discounted price.

A coupon can be for a percentage off the price or a fixed amount off, and it can apply to the entire duration of an order or to a specified amount of payment cycles in the order. A coupon can be created to work for all available plans or for a specific plan only. A coupon can also be limited to apply only if an order hits a minimum subtotal, or limited to the amount of uses available per coupon.

Create new coupons using the createCoupon() function or through the dashboard. You can learn more about creating coupons here.

Once the coupon is applied, taxes are recalculated if taxes are configured for the site.

applyCoupon() makes a change to the order itself. To see what the price would be if the coupon is applied, but without making an actual change to the order, use the previewOfflineOrder(), previewOnlineOrder(), or previewPrice() functions.

When a coupon applies to the entire order, there is a single price for the repeating payment cycle for the entire duration of the order.

Example: A 10% off coupon that applies to the entire order.

     "prices": [{
       "duration": {
         "cycleFrom": 1
       },
       "price": {
         "subtotal": "14.99",
         "coupon": {
           "code": "BACKTOSHAPE22",
           "amount": "1.5",
           "_id": "52f73ce1-9e31-40f7-b5d4-a621b4b4057d"
         },
         "discount": "1.5",
         "total": "13.49",
         "currency": "USD"
         }
       }]

javascript | Copy Code

When a coupon only applies to some payment cycles of the order, there is a price for the period when the coupon applies and a separate price for the rest of the time.

Example: A coupon that rewards the first month free.

   "prices": [
     {
       "duration": {
         "cycleFrom": 1,
         "numberOfCycles": 1
       },
       "price": {
         "subtotal": "74.99",
         "coupon": {
           "code": "ONEMONTHFREE",
           "amount": "74.99",
           "_id": "5061dd91-8cfc-4948-aae2-66fbc4b31af7"
         },
         "discount": "74.99",
         "total": "0",
         "currency": "EUR"
       }
     },
     {
       "duration": {
         "cycleFrom": 2,
         "numberOfCycles": 2
       },
       "price": {
         "subtotal": "74.99",
         "discount": "0",
         "total": "74.99",
         "currency": "EUR"
       }
     }]

javascript | Copy Code

Syntax

function applyCoupon(orderId: string, couponCode: string): Promise<ApplyCoupon>

applyCoupon Parameters

NAME

TYPE

DESCRIPTION

orderId

string

ID of the order to apply coupon to.

couponCode

string

Coupon code to apply.

Returns

Fulfilled - A preview of the order.

Return Type:

Promise<ApplyCoupon>

NAME

TYPE

DESCRIPTION

order

Order

The order with the coupon applied.

Apply a coupon to an online order

This example applies a $50-off coupon to an order that was created in the frontend.

Copy Code

1/**********************************
2 * Backend code - checkout.web.js *
3 *********************************/
4import { Permissions, webMethod } from 'wix-web-module';
5import { checkout } from 'wix-pricing-plans-backend';
6
7// Sample orderId value: '18629b51-f0a3-4105-b367-c250dad96d83'
8//
9// Sample couponCode value: 'FIFTYOFF'
10export const myApplyCouponFunction = webMethod(Permissions.Anyone, async (orderId, couponCode) => {
11  try {
12    const discountedOrder = await checkout.applyCoupon(orderId, couponCode);
13
14    return discountedOrder;
15  } catch (error) {
16    console.error(error);
17  }
18});
19
20/*****************
21 * Frontend code *
22 *****************/
23import { checkout } from 'wix-pricing-plans-frontend';
24import { myApplyCouponFunction } from 'backend/orders-checkout.web';
25
26$w.onReady(function () {
27	$w('#myOrderButton').onClick((event) => {
28		const planId = "26f474d3-16a5-4891-8076-1f2f44e13021"
29
30    // Create an online order in DRAFT status, and pass the order ID to the applyCoupon() function.
31		checkout.createOnlineOrder(planId)
32		.then((newOrder) => {
33			const id = newOrder._id;
34
35      myApplyCouponFunction(id, 'FIFTYOFF')
36        .then((discountedOrder) => {
37          const discountedPricing = discountedOrder.pricing;
38          const status = discountedOrder.status;
39
40          console.log(discountedPricing, status);
41    			return discountedOrder;
42        });
43		})
44		.catch((error) => {
45			console.error(error);
46		})
47	});
48});
49
50/* Promise resolves to: 
51 * 
52 * {
53 *     "_id": "18629b51-f0a3-4105-b367-c250dad96d83",
54 *     "planId": "26f474d3-16a5-4891-8076-1f2f44e13021",
55 *     "subscriptionId": "6af934ac-0bce-4abc-ab6a-82117b90a6cc",
56 *     "wixPayOrderId": "31ba9b82-8530-4009-8d7c-c8f83c6e9d12",
57 *     "buyer": {
58 *         "memberId": "0c9bca47-1f00-4b92-af1c-7852452e949a",
59 *         "contactId": "0c9bca47-1f00-4b92-af1c-7852452e949a"
60 *     },
61 *     "priceDetails": {
62 *         "subtotal": "25.0",
63 *         "discount": "25.0",
64 *         "total": "0",
65 *         "planPrice": "25",
66 *         "currency": "USD",
67 *         "subscription": {
68 *             "cycleDuration": {
69 *                 "count": 1,
70 *                 "unit": "MONTH"
71 *             },
72 *             "cycleCount": 12
73 *         },
74 *         "coupon": {
75 *             "code": "FIFTYOFF",
76 *             "amount": "25.0",
77 *             "_id": "0a499915-7099-4179-a19a-4cc66044f8e3"
78 *         }
79 *     },
80 *     "pricing": {
81 *         "subscription": {
82 *             "cycleDuration": {
83 *                 "count": 1,
84 *                 "unit": "MONTH"
85 *             },
86 *             "cycleCount": 12
87 *         },
88 *         "prices": [
89 *             {
90 *                 "duration": {
91 *                     "cycleFrom": 1,
92 *                     "numberOfCycles": 2
93 *                 },
94 *                 "price": {
95 *                     "subtotal": "25.0",
96 *                     "coupon": {
97 *                         "code": "FIFTYOFF",
98 *                         "amount": "25.0",
99 *                         "_id": "0a499915-7099-4179-a19a-4cc66044f8e3"
100 *                     },
101 *                     "discount": "25.0",
102 *                     "total": "0",
103 *                     "currency": "USD"
104 *                 }
105 *             },
106 *             {
107 *                 "duration": {
108 *                     "cycleFrom": 3,
109 *                     "numberOfCycles": 10
110 *                 },
111 *                 "price": {
112 *                     "subtotal": "25",
113 *                     "discount": "0",
114 *                     "total": "25",
115 *                     "currency": "USD"
116 *                 }
117 *             }
118 *         ]
119 *     },
120 *     "type": "ONLINE",
121 *     "orderMethod": "UNKNOWN",
122 *     "status": "DRAFT",
123 *     "autoRenewCanceled": false,
124 *     "lastPaymentStatus": "UNPAID",
125 *     "startDate": "2022-09-12T22:33:21.094Z",
126 *     "endDate": "2023-09-12T22:33:21.094Z",
127 *     "pausePeriods": [],
128 *     "earliestEndDate": "2023-09-12T22:33:21.094Z",
129 *     "currentCycle": {
130 *         "index": 1,
131 *         "startedDate": "2022-09-12T22:33:21.094Z",
132 *         "endedDate": "2022-10-12T22:33:21.094Z"
133 *     },
134 *     "planName": "Annual plan",
135 *     "planDescription": "",
136 *     "planPrice": "25",
137 *     "_createdDate": "2022-09-12T22:33:21.094Z",
138 *     "_updatedDate": "2022-09-12T22:33:23.686Z"
139 * }
140 */