With Orders, you can manage orders and create offline orders. You can also change access to content on Wix or external apps upon plan purchase or cancellation.
The Orders API allows your app to:
- Create an offline order.
- Preview an order to show price, tax, and other details.
- Extend an order's duration or cancel an order.
- Pause and resume an order.
- Order: A purchase of a subscription to a Pricing Plan. The order details include price, duration, and billing schedule information. Orders can be free. Orders can also be partially free using free trial days.
- Offline Order: A purchase of a subscription to a Pricing Plan where the payment isn't handled via Wix. This type of order can be created via API.
- Online Order: A purchase of a subscription to a Pricing Plan where the payment is handled via Wix. This type of order can't be created via API.
- Buyer: A customer.
- This API supports creating offline orders only. Pricing plan orders created via API can't be paid for using the Wix Payment system.
- The application of tax to orders is defined at the site level, and isn't accessible via API. If site owners need to collect tax, they must set up tax collection manually.
This article shares a possible use case your app 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 app's implementation.
Site owners can use your app to reach out to their customers and send a confirmation email that a payment was successful. To begin, create an email template to use for these messages. Site owners can also design their own with their email marketing dashboard.
To listen for successful payments and send a confirmation email to the customer, follow this flow:
- Listen for any new payments using the Payment Webhook.
- When the webhook is triggered, check for a
wixAppId
of1522827f-c56c-a5c9-2ac9-00f9e6ae12d3
(the Wix App ID for Pricing Plans) and extract thewixAppOrderId
. - Call Get Order using the
wixAppOrderId
as theid
for the order to retrieve. - Extract the
order.buyer.memberId
to retrieve the buyer'smemberId
. - Use the ID to Get Member and extract the member's
loginEmail
. - Call Query Email Subscriptions and filter by the email address to confirm that the member has agreed to receive emails from the site owner.
- Use Get or Create Conversation and Send Message to send an email to the buyer.
- ONLINE: The buyer purchased the plan using the site.
- OFFLINE: The buyer made a manual, offline purchase without using the site.
- DRAFT: Order has been initiated but payment hasn't been processed yet. The plan isn't yet available for use to the buyer.
- PENDING: Order has been purchased and its start date is set in the future.
- ACTIVE: Order has been processed. The plan is available for use.
- PAUSED: Order, and use of the plan, is paused. The order, and use of the plan, can be resumed.
- ENDED: Order has completed its duration and is no longer available for use.
- CANCELED: Order has been canceled.
- PAID: The last payment was paid.
- REFUNDED: The last payment was refunded.
- FAILED: The last payment transaction didn't complete.
- UNPAID: The last payment wasn't paid.
- PENDING: Awaiting payment.
- NOT_APPLICABLE: No payment was necessary. For example, for free plans or free trials.
Retrieves an order by ID.
Syntax
Returns orders for currently logged in member.
Syntax
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 offline
in type
. 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.
Handle payment for an offline order in 1 of 2 ways:
- When creating the order, select
true
in thepaid
request parameter. - After creation, use Mark As Paid to mark the order as paid.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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, use Get Price Preview.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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.
Buyers do not have to be logged in to preview the price, as such, the details returned are not buyer-specific. To generate a preview of a purchase for a specific buyer, use Get Offline Order Preview.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves an order by ID.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Extends the duration of a pricing plan order by postponing the order's endDate
.
New endDate
must be later than the order's current endDate
. Can't postpone orders that are unlimited.
Can't postpone an order while it is PAUSED
.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Retrieves a list of orders and details, given the provided 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.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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 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:Syntax
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.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Pauses an order.
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
. Can only pause orders with an ACTIVE
status.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Resumes a paused order.
Updates endDate
by adding the time the plan was paused.
For orders with recurring payments, it also restarts the payment schedule.
Use Pause Order to pause an order.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Triggered when an order is canceled.
This webhook is triggered either immediately or at the end of the current payment cycle, as follows:
- If the order is canceled and
effectiveAt
is set toIMMEDIATELY
, the webhook is triggered immediately when canceled. - If the order is canceled and
effectiveAt
is set toNEXT_PAYMENT_DATE
, the webhook is triggered at the end of the current payment cycle. In this case, the Order Auto Renew Canceled Webhook is triggered immediately.
Event Body
Triggered when an order is created.
Event Body
Triggered when an order is updated.
This is a general webhook that is triggered when any update is made to an order. More specific webhooks are also triggered for the same originating events.
Order event | Also triggered |
---|---|
Order is paid for. | Order Purchased Webhook |
Free or offline order is created. | Order Purchased Webhook |
Order reaches its startDate . | Order Started Webhook |
Order reaches its endDate . | Order Ended Webhook |
New payment cycle of an order starts. | Order Cycle Started Webhook |
Offline order is marked as paid. | Order Marked As Paid Webhook |
endDate of the order is postponed. | Order End Date Postponed Webhook |
Order is paused. | Order Paused Webhook |
Paused order is resumed. | Order Resumed Webhook |
Order is canceled. | Order Canceled Webhook |
Order is canceled and effectiveAt is set to NEXT_PAYMENT_DATE . | Order Auto Renew Canceled Webhook |
Event Body
Triggered when an order is purchased.
This webhook is triggered for any of the following events:
- Order is paid in full.
- At least 1 order cycle payment is paid for.
- Offline order is created, even if not yet marked as paid.
- Free order is created.
Event Body
Triggered when an order reaches its startDate
. Applies to both purchased and free orders.
Event Body
Triggered at the start of a new payment cycle for an existing order.
This webhook is not triggered at the initial start of an offline order.
Event Body
Triggered when an order is canceled and effectiveAt
is set to NEXT_PAYMENT_DATE
.
This webhook is not triggered in the following scenarios:
- When an order is canceled and
effectiveAt
is set toIMMEDIATELY
. Instead, at the time of cancellation, Order Canceled is triggered. - When an order expires at the end of the current payment cycle because it was canceled and
effectiveAt
was set toNEXT_PAYMENT_DATE
. Instead, at the time of expiration, Order Canceled and Order Ended are triggered.
Event Body
Triggered when an order ends.
This webhook is triggered:
- When an order expires at the end of the current payment cycle.
- When an order is canceled and
effectiveAt
is set toIMMEDIATELY
..
Event Body
Triggered when an order's endDate
is postponed.
Event Body
Triggered when an offline order is marked as paid.
Event Body
Triggered when an order is paused.
Event Body
Triggered when a paused order is resumed.