Was this helpful?
Yes
No

Setup

To use the Orders API, install the @wix/pricing-plans package using npm or Yarn:

Copy
1
npm install @wix/pricing-plans

or

Copy
1
yarn add @wix/pricing-plans

Then import { orders } from @wix/pricing-plans:

Copy
1
import { orders } from '@wix/pricing-plans'
Was this helpful?
Yes
No

cancelOrder( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Cancels an existing order.

The cancelOrder() function returns a Promise that resolves when the order is successfully canceled.

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

Canceling an order changes the order status to CANCELED.

Canceling during the free trial period.

When a site owner cancels an ordered plan during the free trial period, they choose 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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function cancelOrder(_id: string, effectiveAt: CancellationEffectiveAt): Promise<void>
Method Parameters
_idstringRequired

Order ID.


effectiveAtCancellationEffectiveAtRequired
3 enum supported values:
IMMEDIATELYNEXT_PAYMENT_DATEUNDEFINED

When the order is canceled.

One time orders can only be canceled immediately. Supported values:

  • "IMMEDIATELY": The order is canceled immediately.
  • "NEXT_PAYMENT_DATE": The order is canceled at the next payment date.
Was this helpful?
Yes
No

createOfflineOrder( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Creates an order for a buyer who purchased the plan with an offline transaction.

The createOfflineOrder() function returns a Promise that resolves to an order object when the order has been created.

Payment of an offline order is handled in 1 of 2 ways.

  • When creating the order, select true in the paid request parameter.
  • After creation, with the markAsPaid() function.

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

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

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function createOfflineOrder(planId: string, memberId: string, options: CreateOfflineOrderOptions): Promise<CreateOfflineOrderResponse>
Method Parameters
planIdstringRequired

ID of the plan being ordered. See Plans for more information about plan IDs


memberIdstringRequired

ID of the member ordering the plan.


optionsCreateOfflineOrderOptions

Options for creating an offline order.

Returns
Return Type:Promise<CreateOfflineOrderResponse>
Was this helpful?
Yes
No

getOfflineOrderPreview( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Provides a preview of an offline order as if it was purchased.

The getOfflineOrderPreview() function returns a Promise that resolves to a temporary preview of the offline order.

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's _id and subscriptionId properties are displayed as a string of multiple zero characters (000000-0000).

If taxes are configured for the site, taxes are applied to the preview. If not, tax previews as null.

You can preview the order to check purchase limitations, but the limitations are not enforced for the preview. 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. Thus function is not available to the buyer. You specify the member ID for the buyer whose order should be previewed. To get a general price preview for a plan that's not buyer-specific, use the getPricePreview() function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
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.


optionsGetOfflineOrderPreviewOptions

Options for previewing the offline order.

Returns
Return Type:Promise<GetOfflineOrderPreviewResponse>
Was this helpful?
Yes
No

getPricePreview( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves a preview of an order's pricing as if it was purchased.

The getPricePreview() function returns a Promise that resolves to a temporary preview of the order's price.

The price preview uses the same logic for calculating prices as used when purchasing a plan, but the preview is not saved. If taxes are configured for the site, taxes are applied to the preview. If not, the tax previews as null.

Buyers do not have to be logged in to preview the price, as such, the details returned by this function are not buyer-specific. To generate a preview of a purchase for a specific-buyer, use the getOfflineOrderPreview().

Permission Scopes

For app development, you must have one of the following permission scopes:
Read Pricing Plans
Manage Orders
Manage Bookings Services and Settings
Read Orders
Manage Pricing Plans
Learn more about permission scopes.
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>
Was this helpful?
Yes
No

managementGetOrder( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves an order by ID.

The managementGetOrder() function returns a Promise that resolves to information about the specified order.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Bookings Services and Settings
Read Orders
Learn more about permission scopes.
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>
Was this helpful?
Yes
No

managementListOrders( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Lists pricing plan orders.

The managementListOrders() function returns a Promise that resolves to a list of up to 50 pricing plan orders. You can specify options for filtering, sorting, and paginating the results.

This function returns the orders on the site. To list orders for the currently logged-in member, use memberListOrders().

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Manage Bookings Services and Settings
Read Orders
Learn more about permission scopes.
Copy
function managementListOrders(options: ManagementListOrdersOptions): Promise<ListOrdersResponse>
Method Parameters
optionsManagementListOrdersOptions

Filtering, sorting, and pagination options.

Returns
Return Type:Promise<ListOrdersResponse>
Was this helpful?
Yes
No

markAsPaid( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Marks an offline order as paid.

The markAsPaid() function returns a Promise that resolves when the offline order is successfully marked as paid.

The entire order is marked as paid, even if the order's payments are recurring.

Note: Marking separate payment cycles as paid is not yet supported. 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 make an offline order as paid twice.
  • Mark an online order as paid. The markAsPaid() function is supported for offline orders only.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function markAsPaid(_id: string): Promise<void>
Method Parameters
_idstringRequired

Order ID.

Was this helpful?
Yes
No

memberGetOrder( )

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

The memberGetOrder() function returns a Promise that resolves to information about a specified order for the currently logged-in member.

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>
Was this helpful?
Yes
No

memberListOrders( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Lists orders for the currently logged-in member.

The memberListOrders() function returns a Promise that resolves to a list of up to 100 pricing plan orders.

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

Filtering, sorting, and pagination options.

Returns
Return Type:Promise<MemberListOrdersResponse>
Was this helpful?
Yes
No

pauseOrder( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Pauses a pricing plan order.

The pauseOrder() function returns a Promise that resolves when the order is successfully paused.

For orders with recurring payments, pauseOrder() also pauses the payment schedule. Buyers are not charged when an order is paused. Use pauseOrder(), for example, if the buyer is away and would like to put their pricing plan membership on hold until they return. Pausing an order affects the end date of the order by adding the time the order is paused to the endDate. You can only pause orders with an "ACTIVE" status.

Pausing an order causes the following changes:

  • The order status changes to "PAUSED".
  • The pausePeriods array is updated.

The endDate and the earliestEndDate for the order are adjusted to include the pause period when the order is resumed.

Paused orders can be continued with the resumeOrder() function.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function pauseOrder(_id: string): Promise<void>
Method Parameters
_idstringRequired

Order ID.

Was this helpful?
Yes
No

postponeEndDate( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Extends the duration of a pricing plan order by postponing the order's endDate.

The postponeEndDate() function returns a Promise that resolves when the order's end date is successfully changed.

The new end date and time must be later than the order's current endDate.

Postponing the end date of an order does not impact payments. For example, if the pricing plan is for a membership to an online lecture series, and you want to extend the duration of the series because the lecturer could not attend some sessions, you can postpone the end date of the orders for all relevant participants. The participants will not be billed additionally.

Postponing an order causes the following changes:

  • The endDate for the order is adjusted to the new end date.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function postponeEndDate(_id: string, endDate: ): Promise<void>
Method Parameters
_idstringRequired

Order ID.


endDateRequired

New end date and time.

Must be later than the current end date and time.

Was this helpful?
Yes
No

requestCancellation( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Starts the process of canceling an order.

The requestCancellation() function returns a Promise that resolves when the order cancellation is successfully requested.

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 occurs immediately after the request is processed.

Requesting an order cancellation starts the cancellation process. 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.

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

Order ID.


effectiveAtCancellationEffectiveAtRequired
3 enum supported values:
IMMEDIATELYNEXT_PAYMENT_DATEUNDEFINED

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

Supported values:

  • "IMMEDIATELY": Indicates that the order should be canceled immediately.
  • "NEXT_PAYMENT_DATE": Indicates that the order be canceled at the next payment date.
Was this helpful?
Yes
No

resumeOrder( )

Developer Preview

This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Resumes a paused pricing plan order.

The resumeOrder() function returns a Promise that resolves when a paused order is successfully resumed.

For orders with recurring payments, resumeOrder() also restarts the payment schedule.

Resuming an order causes the following changes:

  • The order status changes to "ACTIVE".
  • The pausePeriods array is updated.
  • The endDate for the order is adjusted to include the pause period.
  • The earliestEndDate is adjusted to include the pause period. (This property is reserved for future use).

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.
Copy
function resumeOrder(_id: string): Promise<void>
Method Parameters
_idstringRequired

Order ID.

Was this helpful?
Yes
No