This article shares a possible use case you could support, as well as a sample flow that could support the use case. This can be a helpful jumping off point as you plan your implementation.
You can create an implementation that sends a Wix Inbox confirmation email to customers that a payment was successful.
To listen for successful payments and send a confirmation email to the customer, follow this flow:
wixAppId
of 1522827f-c56c-a5c9-2ac9-00f9e6ae12d3
(the Wix App ID for Pricing Plans) and extract the wixAppOrderId
.wixAppOrderId
as the id
for the order to retrieve.order.buyer.memberId
to retrieve the buyer's memberId
.memberId
and extract the member's loginEmail
.Cancels an existing order.
For orders with recurring payments, a cancellation can be set to occur either IMMEDIATELY
or at the NEXT_PAYMENT_DATE
.
For orders with one-time payments, a cancellation can only be set for IMMEDIATELY
.
When a buyer cancels their order during the free trial period, the buyer's subscription expires at the end of the free trial period and they will not be billed. The buyer may continue using the benefits until the end of the free trial period.
When a Wix user cancels an ordered plan during the free trial period, they choose whether to apply the cancellation
IMMEDIATELY
or at the NEXT_PAYMENT_DATE
. Canceling IMMEDIATELY
will end 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.
function cancelOrder(
_id: string,
effectiveAt: CancellationEffectiveAt,
): Promise<void>;
Order ID.
Required. When the order will be canceled. One-time orders can only be canceled IMMEDIATELY
.
import { orders } from "@wix/pricing-plans";
async function cancelOrder(id, effectiveAt) {
const response = await orders.cancelOrder(id, effectiveAt);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Creates an order for a buyer who purchased the plan with an offline transaction.
An offline order is handled off of the Wix site and is marked as type
: offline
. If a pricing plan
has a limit on the amount of purchases per buyer, that limit is ignored for offline orders.
Tax is only applied if the site has it configured.
When creating a free offline order:
The order's status is set to "PENDING"
if the start date is in the future. Otherwise, the status is set to "ACTIVE"
.
The order's last payment status is set to "NOT_APPLICABLE"
. "
When creating a non-free offline order:
The order's status is set to "PENDING"
if the start date is in the future. Otherwise, the status is set to "ACTIVE"
.
The order's last payment status is set to "UNPAID"
or "PAID"
based on the data passed in the paid
boolean in the request.
Payment for an offline order can be set in 1 of 2 ways:
paid
: true
.function createOfflineOrder(
planId: string,
memberId: string,
options: CreateOfflineOrderOptions,
): Promise<CreateOfflineOrderResponse>;
ID of the plan being ordered, from the Plans API.
ID of the member ordering the plan, from the Members API.
Options for creating an offline order.
import { orders } from "@wix/pricing-plans";
async function createOfflineOrder(planId, memberId, options) {
const response = await orders.createOfflineOrder(planId, memberId, options);
}
There are 8 errors with this status code.
This method may also return standard errors. Learn more about standard Wix errors.
Creates an online order for a site member.
If this method is called by a site member (SDK | REST), the plan is automatically ordered on behalf of that site member. Otherwise, you must specify onBehalf.memberId
in your call.
When an online order is created, but payment hasn't been processed, its status is set to DRAFT
. After the payment has been processed, if the start date is in the future the order's status is set to PENDING
. Otherwise, it's set to ACTIVE
.
function createOnlineOrder(
planId: string,
options: CreateOnlineOrderOptions,
): Promise<CreateOnlineOrderResponse>;
Plan ID.
import { orders } from "@wix/pricing-plans";
async function createOnlineOrder(planId, options) {
const response = await orders.createOnlineOrder(planId, options);
}
There are 8 errors with this status code.
This method may also return standard errors. Learn more about standard Wix errors.
Performs a dry run of a purchase and provides an order preview.
The preview uses the same logic as purchasing a plan, but the preview is not saved. Because an order is not actually
created, the preview order's orderId
and subscriptionId
are displayed as a string of multiple zero characters
(000000-0000
). Tax is only calculated if the site has it configured.
If a pricing plan has a limit on the amount of purchases per buyer, that limit is not considered for generating the preview.
But, if that limit has been reached and this order would then exceed the amount of purchases permitted for this buyer, then
purchaseLimitExceeded
will return as true
.
To get a general price preview for a plan that's not buyer-specific, call Get Price Preview.
function getOfflineOrderPreview(
planId: string,
memberId: string,
options: GetOfflineOrderPreviewOptions,
): Promise<GetOfflineOrderPreviewResponse>;
ID of the plan of the previewed order.
Member ID of the buyer the previewed order is for, from the Members API.
Options for previewing the offline order.
import { orders } from "@wix/pricing-plans";
async function getOfflineOrderPreview(planId, memberId, options) {
const response = await orders.getOfflineOrderPreview(
planId,
memberId,
options,
);
}
There are 8 errors with this status code.
This method may also return standard errors. Learn more about standard Wix errors.
Returns an order
object that represents a potential online order for a site member.
You can use this method to show a site member a preview of an online order before creating it.
This method must be called using the site member identity (SDK | REST). Therefore, Wix apps can't currently call this method using REST.
function getOnlineOrderPreview(
planId: string,
options: GetOnlineOrderPreviewOptions,
): Promise<GetOnlineOrderPreviewResponse>;
Plan ID.
import { orders } from "@wix/pricing-plans";
async function getOnlineOrderPreview(planId, options) {
const response = await orders.getOnlineOrderPreview(planId, options);
}
There are 8 errors with this status code.
This method may also return standard errors. Learn more about standard Wix errors.
Retrieves a plan's pricing.
The price preview uses the same logic as purchasing a plan, but the preview is not saved. Tax is only applied if the site has it configured. The price is returned in the pricing model format used for orders. Learn more about pricing models (REST|SDK).
Buyers do not have to be logged in to preview the price, and as such, the details returned are not buyer-specific. To generate a preview of a purchase for a specific buyer, call Get Offline Order Preview.
function getPricePreview(
planId: string,
options: GetPricePreviewOptions,
): Promise<GetPricePreviewResponse>;
ID of plan to preview.
Options for getting a price preview.
import { orders } from "@wix/pricing-plans";
async function getPricePreview(planId, options) {
const response = await orders.getPricePreview(planId, options);
}
There are 8 errors with this status code.
This method may also return standard errors. Learn more about standard Wix errors.
Retrieves an order by ID.
function managementGetOrder(
_id: string,
options: ManagementGetOrderOptions,
): Promise<GetOrderResponse>;
Order ID.
Options to use when getting an order.
import { orders } from "@wix/pricing-plans";
async function managementGetOrder(id, options) {
const response = await orders.managementGetOrder(id, options);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Retrieves a list of up to 50 pricing plan orders and details, given the specified sorting and filtering.
By default, this endpoint will retrieve all orders and return them sorted by createdDate
in DESC
, descending order.
sort.fieldName
supports endDate
and createdDate
fields and defaults to ASC
, ascending order.
function managementListOrders(
options: ManagementListOrdersOptions,
): Promise<ListOrdersResponse>;
Filtering, sorting, and pagination options.
import { orders } from "@wix/pricing-plans";
async function managementListOrders(options) {
const response = await orders.managementListOrders(options);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Marks an offline order as paid.
Note: Marking separate payment cycles as paid is not yet supported. The entire order will be marked as paid. Subsequent offline payments do trigger events and emails, but are not registered as additional offline payments.
Marking an offline order as paid causes the following changes:
lastPaymentStatus
changes to "PAID"
."PENDING"
or "ACTIVE"
, depending on the order's startDate
.An error occurs if you attempt to:
function markAsPaid(_id: string): Promise<void>;
Order ID.
import { orders } from "@wix/pricing-plans";
async function markAsPaid(id) {
const response = await orders.markAsPaid(id);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Retrieves an order for the currently logged-in member by ID.
function memberGetOrder(
_id: string,
options: MemberGetOrderOptions,
): Promise<Order>;
Order ID.
Options for getting a logged-in member's order.
import { orders } from "@wix/pricing-plans";
async function memberGetOrder(id, options) {
const response = await orders.memberGetOrder(id, options);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Retrieves a list of up to 100 pricing plan orders for currently logged-in member.
function memberListOrders(
options: MemberListOrdersOptions,
): Promise<MemberListOrdersResponse>;
Filtering, sorting, and pagination options.
import { orders } from "@wix/pricing-plans";
async function memberListOrders(options) {
const response = await orders.memberListOrders(options);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Pauses an order. Calling this method changes the order status to "PAUSED"
and updates the pausePeriods
array.
Only orders with status
: ACTIVE
can be paused.
For orders with recurring payments, it also pauses the payment schedule. Buyers are not charged when an order is paused.
Pausing an order affects the end date of the order by adding the time the order is paused to the endDate
.
The endDate
and the earliestEndDate
for the order are adjusted to include the pause period when the order is resumed.
To resume a paused order, call Resume Order.
function pauseOrder(_id: string): Promise<void>;
Order ID.
import { orders } from "@wix/pricing-plans";
async function pauseOrder(id) {
const response = await orders.pauseOrder(id);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Extends the duration of a pricing plan order by postponing the order's endDate
. Postponing the end date of an order does not impact payments.
New endDate
must be later than the order's current endDate
. Can't postpone orders that are unlimited.
Can't postpone an order with status
: PAUSED
.
function postponeEndDate(_id: string, endDate: Date): Promise<void>;
Order ID.
New end date and time.
Must be later than the current end date and time.
import { orders } from "@wix/pricing-plans";
async function postponeEndDate(id, endDate) {
const response = await orders.postponeEndDate(id, endDate);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.
Cancels an order. Recurring orders can be canceled either immediately or at the next payment date. One time orders can only be canceled immediately.
There may be some operations that continue to be processed before the status of the order is changed to "CANCELED"
. For example, payments might need to be refunded before the order is fully canceled.
Canceling during the free trial period: When a buyer cancels their order during the free trial period, the buyer's subscription expires at the end of the free trial period and they won't be billed. The buyer may continue using the benefits until the end of the free trial period.
Note: This method requires visitor or member authentication.
function requestCancellation(
_id: string,
effectiveAt: CancellationEffectiveAt,
): Promise<void>;
Order ID.
Required. Whether to cancel the order effective immediately or at the next payment date. One-time orders can only be canceled immediately.
import { orders } from "@wix/pricing-plans";
async function requestCancellation(id, effectiveAt) {
const response = await orders.requestCancellation(id, effectiveAt);
}
This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.