Orders Service
Deprecation Notice:
Stores Orders API has been replaced with eCommerce Orders API and will be removed on September 4, 2024.
Learn more about migrating from Wix Stores to Wix eCommerce.
About This API
Stores Orders API allows third party apps to create and manage orders for Wix store owners.
Use this API to:
- Query the orders in the store
- Get a specific order
- Get notifications (via webhook) about new orders
- Create and update orders
Order Types
-
Shipping orders: Order and shipment of any selection of products from the store's catalog.
-
Pickup orders: Order of any selection of products from the store's catalog for user pickup.
-
Point of Sale (POS) orders: Sale consisting only of price and partial billing information, of products not included in the store's catalog.
Filter and Sort
Query Language
Endpoints that allow querying follow these format guidelines.
Fields That Allow Filtering
Field | Operators | Sorting Allowed |
---|---|---|
dateCreated | $eq,$ne,$hasSome,$lt,$lte,$gt,$gte | Allowed |
lastUpdated | $eq,$ne,$hasSome,$lt,$lte,$gt,$gte | Allowed |
paymentStatus | $eq,$ne,$hasSome | |
archived | $eq,$ne | |
number | $eq,$ne,$hasSome,$lt,$lte,$gt,$gte | Allowed |
fulfillmentStatus | $eq,$ne,$hasSome | |
id | $eq,$ne,$hasSome | |
lineItems.productId | $eq,$ne,$hasSome,$hasAll | |
lineItems.name | $eq,$ne,$hasSome,$hasAll | |
billingInfo.address.fullName | $eq,$ne,$hasSome,$contains,$startsWith | |
buyerInfo.id | $eq,$ne,$hasSome | |
channelInfo.type | $eq,$ne,$hasSome | |
enteredBy.id | $eq,$ne,$hasSome | |
channelInfo.externalOrderId | $eq,$ne,$hasSome |
** Note that "HasSome" is same as the operator "IN" in SQL
Examples
Get all paid orders
1curl 'https://www.wixapis.com/stores/v2/orders/query' --data-binary '{"query":{"filter":"{\"paymentStatus\": \"PAID\"}"}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Get all orders, sorted by creation time
1curl 'https://www.wixapis.com/stores/v2/orders/query' --data-binary '{"query":{"sort":"[{\"dateCreated\": \"asc\"}]"}}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Get orders updated within a specific timeframe
1curl 'https://www.wixapis.com/stores/v2/orders/query' --data-binary '{"query": {"filter": "{\"$and\": [{\"lastUpdated\":{\"$lte\":1588110826000}}, {\"lastUpdated\":{\"$gte\":1585518845000}}]}", "sort": "[{\"number\":\"asc\"}]" }}' -H 'Content-Type: application/json' -H 'Authorization: XXX'
Get orders by IDs
1curl 'https://www.wixapis.com/stores/v2/orders/query' --data-binary '{"query":{"filter":"{\"id\": {\"$hasSome\": [\"ORDER_ID_1\",\"ORDER_ID_2\"]}}"}}' -H 'Content-Type: application/json' -H 'Authorization: xxx'
Edit Order/Draft Orders API Migration Guide
Notes:
- This migration is relevant for all apps that currently use the Stores Orders API.
- The Stores Orders API will soon be deprecated in favor of the eCommerce Orders API.
We’re introducing a new Wix eCommerce Orders API that enables business owners to meet new customer needs and provide better customer service. This will eventually replace the existing Stores Orders API. This quick guide will help you to make sure your app is ready for the migration.
New object and webhook structures
The structure of the eCommerce Order object is different from the Stores Order object. You can learn more about these structural changes here.
The webhook payload structure has also changed. To facilitate your move to these webhooks, have a look at the webhook conversion table.
Users can now edit orders
Customers occasionally make mistakes when placing an order, or they might simply want to make a change to an existing order. This could include adding items, updating prices, revising customer details, and more.
The new eCommerce service includes functionality that lets users edit existing orders. This will be known as Draft Orders when using our REST APIs, and as Edit Order in the dashboard.
When an existing order is edited, the Order Updated Webhook is triggered. This webhook returns the whole order object in the eCommerce order structure, but you can still pass the edited order’s ID to the Stores Orders endpoints if you’d like to fetch the order in the Stores structure.
Impact examples
If a Wix user edits an existing order, depending on your app type you might need your app to be aware of the change. Here are some examples:
- A user changes the quantity of a product item in an existing order. As a result, the number of items to be shipped has changed.
- A user changes the shipping address in an existing order.
- A user adds a new item to an existing order. As a result, the amount to be paid changes.
- A user changes the price of an item in an existing order. As a result, the total payable amount of the order, as well as the payment status can change.
How to add the new Order Updated webhook
- Go to your app in the Wix Developers Center.
- Go to the Webhooks tab in the side menu.
- Click + Add Webhook.
- Select an API Category > Wix eCommerce
- Find and select the Order Updated Webhook
- Add a Callback URL.
- Click Save.
How to test the impact on your app
Edit Order is not yet available publicly, but if you’d like to test the feature yourself and understand any implications it may have for your app, follow these steps:
- Install the EditThisCookie Chrome extension.
- Click + to add a new cookie, select
petri-ovr
and fill out the following fields:
- Value:
specs.stores.OrderEditPageComponent#true
- Domain:
.wix.com
- Secure: Check the box
- HttpOnly: Check the box
- Create a new Wix website with Wix Stores installed (testing this change only works on new sites).
- Refresh the Orders page.
- Navigate to an unfulfilled order in the dashboard.
- Click on the More Actions button in the top right corner.
- Click on Edit Order.
Note:
All orders, including changes committed by Edit Order, are still available in the Stores Orders APIs and webhooks. However, we highly recommend planning your transition to eCommerce Orders and Edit Order/Draft Orders, as the Stores Orders API will be deprecated in the coming months.
This method has been replaced with CreateOrder, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Create Order and will be removed on September 4, 2024.
Creates a new order.
Notes:
- Only orders with the
paymentStatus
parameter set as"PAID"
or"NOT_PAID"
will show up in the site owner's Stores Orders tab in their dashboard. - The
billingInfo.paymentProviderTransactionId
andbillingInfo.paymentMethod
parameters can only be passed when paymentStatus is PAID. - The
billingInfo
.address parameter is required unlesschannelInfo.type: "POS"
. - The
shippingInfo.shipmentDetails.address
parameter is required unless one of the following is true:- The
shippingInfo.pickupDetails
is passed instead channelInfo.type: "POS"
- All order items are of type digital -
lineItems.lineItemType: "DIGITAL"
.
- The
- When passing
lineItems.variantId
,lineItems.options
is required. - When passing
lineItems.productId
,lineItem.lineItemType
is limited to"PHYSICAL"
. - When not passing
lineItems.productId
,lineItem.lineItemType
is limited to"CUSTOM_AMOUNT_ITEM"
.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with UpdateOrder, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Update Order and will be removed on September 4, 2024.
Updates the email address of a specified order's billing info. If shipping was selected as the delivery method, shipping info email will also be updated.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with UpdateOrder, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Update Order and will be removed on September 4, 2024.
Updates the shipping address of a specified order.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with GetOrder, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Get Order and will be removed on September 4, 2024.
Returns an order with the provided ID.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with SearchOrders, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Search Orders and will be removed on September 4, 2024.
Returns a list of up to 100 orders, given the provided paging, sorting and filters. See Stores Pagination for more information. Hidden orders are not returned.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with CreateFulfillment, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Create Fulfillment and will be removed on September 4, 2024.
Creates a fulfillment (a subset of an order, with line items that are being shipped together) based on the body parameters passed with the request. If the site owner has requested it, calling this request will trigger an email to the customer (based on the Wix store settings).
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with UpdateFulfillment, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Update Fulfillment and will be removed on September 4, 2024.
Updates an existing fulfillment.
Permission Scopes
For app development, you must have one of the following permission scopes:This method has been replaced with DeleteFulfillment, and will be removed on September 4, 2024.
Deprecation Notice:
This endpoint has been replaced with eCommerce Delete Fulfillment and will be removed on September 4, 2024.
Deletes an existing fulfillment.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order Approved Event and will be removed on September 4, 2024.
Triggered when an order is created.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order Payment Status Updated Event and will be removed on September 4, 2024.
Triggered when an order is paid.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order Canceled Event and will be removed on September 4, 2024.
Triggered when an order is canceled.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order Transactions Updated Event and will be removed on September 4, 2024.
Triggered when an order is refunded.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order With Fulfillments Updated Event and will be removed on September 4, 2024.
Triggered when a tracking number is added to a fulfillment.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order With Fulfillments Updated Event and will be removed on September 4, 2024.
Triggered when a fulfillment is updated.
Permission Scopes
For app development, you must have one of the following permission scopes:Deprecation Notice:
This webhook has been replaced with eCommerce Order With Fulfillments Updated Event and will be removed on September 4, 2024.
Triggered when a fulfillment is deleted.