Orders: Sample Use Case & Flow

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.

Send an email on successful payment of online orders

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:

  1. Listen to the Payment Event.
  2. When the event is triggered, check for a wixAppId of 1522827f-c56c-a5c9-2ac9-00f9e6ae12d3 (the Wix App ID for Pricing Plans) and extract the wixAppOrderId.
  3. Call Get Order using the wixAppOrderId as the id for the order to retrieve.
  4. Extract the order.buyer.memberId to retrieve the buyer's memberId.
  5. Call Get Member with the memberId and extract the member's loginEmail.
  6. Call Query Email Subscriptions and filter by the email address to confirm that the member has agreed to receive emails from the Wix user.
  7. Call Get or Create Conversation and Send Message to send an email to the buyer.
Did this help?

cancelOrder( )


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.

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

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function cancelOrder(
  _id: string,
  effectiveAt: CancellationEffectiveAt,
): Promise<void>;
Method Parameters
_idstringRequired

Order ID.


effectiveAtCancellationEffectiveAtRequired

Required. When the order will be canceled. One-time orders can only be canceled IMMEDIATELY.

JavaScript
import { orders } from "@wix/pricing-plans"; async function cancelOrder(id, effectiveAt) { const response = await orders.cancelOrder(id, effectiveAt); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

createOfflineOrder( )


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:

  • During order creation, set paid: true.
  • After creation, call Mark As Paid.
Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function createOfflineOrder(
  planId: string,
  memberId: string,
  options: CreateOfflineOrderOptions,
): Promise<CreateOfflineOrderResponse>;
Method Parameters
planIdstringRequired

ID of the plan being ordered, from the Plans API.


memberIdstringRequired

ID of the member ordering the plan, from the Members API.


optionsCreateOfflineOrderOptions

Options for creating an offline order.

Returns
Return Type:Promise<CreateOfflineOrderResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function createOfflineOrder(planId, memberId, options) { const response = await orders.createOfflineOrder(planId, memberId, options); }
Errors
428Failed Precondition

There are 8 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

createOnlineOrder( )


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.

Method Declaration
Copy
function createOnlineOrder(
  planId: string,
  options: CreateOnlineOrderOptions,
): Promise<CreateOnlineOrderResponse>;
Method Parameters
planIdstringRequired

Plan ID.


optionsCreateOnlineOrderOptions
Returns
Return Type:Promise<CreateOnlineOrderResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function createOnlineOrder(planId, options) { const response = await orders.createOnlineOrder(planId, options); }
Errors
428Failed Precondition

There are 8 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

getOfflineOrderPreview( )


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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function getOfflineOrderPreview(
  planId: string,
  memberId: string,
  options: GetOfflineOrderPreviewOptions,
): Promise<GetOfflineOrderPreviewResponse>;
Method Parameters
planIdstringRequired

ID of the plan of the previewed order.


memberIdstringRequired

Member ID of the buyer the previewed order is for, from the Members API.


optionsGetOfflineOrderPreviewOptions

Options for previewing the offline order.

Returns
Return Type:Promise<GetOfflineOrderPreviewResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function getOfflineOrderPreview(planId, memberId, options) { const response = await orders.getOfflineOrderPreview( planId, memberId, options, ); }
Errors
428Failed Precondition

There are 8 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

getOnlineOrderPreview( )


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.

Permissions
Manage Bookings Services and Settings
Manage Events
Manage Portfolio
Access Verticals by Automations
Set Up Automations
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
function getOnlineOrderPreview(
  planId: string,
  options: GetOnlineOrderPreviewOptions,
): Promise<GetOnlineOrderPreviewResponse>;
Method Parameters
planIdstringRequired

Plan ID.


optionsGetOnlineOrderPreviewOptions
Returns
Return Type:Promise<GetOnlineOrderPreviewResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function getOnlineOrderPreview(planId, options) { const response = await orders.getOnlineOrderPreview(planId, options); }
Errors
428Failed Precondition

There are 8 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

getPricePreview( )


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.

Permissions
Manage Bookings Services and Settings
Manage Orders
Read Orders
Read Pricing Plans
Manage Events
Access Verticals by Automations
Set Up Automations
Manage Pricing Plans
Manage Portfolio
Manage Restaurants - all permissions
Learn more about app permissions.
Method Declaration
Copy
function getPricePreview(
  planId: string,
  options: GetPricePreviewOptions,
): Promise<GetPricePreviewResponse>;
Method Parameters
planIdstringRequired

ID of plan to preview.


optionsGetPricePreviewOptions

Options for getting a price preview.

Returns
Return Type:Promise<GetPricePreviewResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function getPricePreview(planId, options) { const response = await orders.getPricePreview(planId, options); }
Errors
428Failed Precondition

There are 8 errors with this status code.

This method may also return standard errors. Learn more about standard Wix errors.

Did this help?

managementGetOrder( )


Retrieves an order by ID.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Read Orders
Manage Events
Learn more about app permissions.
Method Declaration
Copy
function managementGetOrder(
  _id: string,
  options: ManagementGetOrderOptions,
): Promise<GetOrderResponse>;
Method Parameters
_idstringRequired

Order ID.


optionsManagementGetOrderOptions

Options to use when getting an order.

Returns
Return Type:Promise<GetOrderResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function managementGetOrder(id, options) { const response = await orders.managementGetOrder(id, options); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

managementListOrders( )


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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Read Orders
Manage Events
Learn more about app permissions.
Method Declaration
Copy
function managementListOrders(
  options: ManagementListOrdersOptions,
): Promise<ListOrdersResponse>;
Method Parameters
optionsManagementListOrdersOptions

Filtering, sorting, and pagination options.

Returns
Return Type:Promise<ListOrdersResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function managementListOrders(options) { const response = await orders.managementListOrders(options); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

markAsPaid( )


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:

  • The order's lastPaymentStatus changes to "PAID".
  • The order's status changes to either "PENDING" or "ACTIVE", depending on the order's startDate.

An error occurs if you attempt to:

  • Mark an already-paid, offline order as paid. You cannot mark an offline order as paid twice.
  • Mark an online order as paid. The Mark as Paid method is supported for offline orders only.
Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function markAsPaid(_id: string): Promise<void>;
Method Parameters
_idstringRequired

Order ID.

JavaScript
import { orders } from "@wix/pricing-plans"; async function markAsPaid(id) { const response = await orders.markAsPaid(id); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

memberGetOrder( )


Retrieves an order for the currently logged-in member by ID.

Method Declaration
Copy
function memberGetOrder(
  _id: string,
  options: MemberGetOrderOptions,
): Promise<Order>;
Method Parameters
_idstringRequired

Order ID.


optionsMemberGetOrderOptions

Options for getting a logged-in member's order.

Returns
Return Type:Promise<Order>
JavaScript
import { orders } from "@wix/pricing-plans"; async function memberGetOrder(id, options) { const response = await orders.memberGetOrder(id, options); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

memberListOrders( )


Retrieves a list of up to 100 pricing plan orders for currently logged-in member.

Method Declaration
Copy
function memberListOrders(
  options: MemberListOrdersOptions,
): Promise<MemberListOrdersResponse>;
Method Parameters
optionsMemberListOrdersOptions

Filtering, sorting, and pagination options.

Returns
Return Type:Promise<MemberListOrdersResponse>
JavaScript
import { orders } from "@wix/pricing-plans"; async function memberListOrders(options) { const response = await orders.memberListOrders(options); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

pauseOrder( )


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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function pauseOrder(_id: string): Promise<void>;
Method Parameters
_idstringRequired

Order ID.

JavaScript
import { orders } from "@wix/pricing-plans"; async function pauseOrder(id) { const response = await orders.pauseOrder(id); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

postponeEndDate( )


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.

Authentication
  • When developing websites or building an app with Blocks, this method may require elevated permissions, depending on the identity of the user calling it and the calling user’s permissions.
  • When building apps without Blocks or for headless projects, you can only call this method directly when authenticated as a Wix app or Wix user identity. When authenticated as a different identity, you can call this method using elevation.
  • Elevation permits users to call methods they typically cannot access. Therefore, you should only use it intentionally and securely.
Permissions
Manage Orders
Learn more about app permissions.
Method Declaration
Copy
function postponeEndDate(_id: string, endDate: Date): Promise<void>;
Method Parameters
_idstringRequired

Order ID.


endDateDateRequired

New end date and time.

Must be later than the current end date and time.

JavaScript
import { orders } from "@wix/pricing-plans"; async function postponeEndDate(id, endDate) { const response = await orders.postponeEndDate(id, endDate); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

requestCancellation( )


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.

Method Declaration
Copy
function requestCancellation(
  _id: string,
  effectiveAt: CancellationEffectiveAt,
): Promise<void>;
Method Parameters
_idstringRequired

Order ID.


effectiveAtCancellationEffectiveAtRequired

Required. Whether to cancel the order effective immediately or at the next payment date. One-time orders can only be canceled immediately.

JavaScript
import { orders } from "@wix/pricing-plans"; async function requestCancellation(id, effectiveAt) { const response = await orders.requestCancellation(id, effectiveAt); }
Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?