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:

  1. Query the orders in the store
  2. Get a specific order
  3. Get notifications (via webhook) about new orders
  4. 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.

Was this helpful?
Yes
No

Filter and Sort

Query Language

Endpoints that allow querying follow these format guidelines.

Fields That Allow Filtering

FieldOperatorsSorting Allowed
dateCreated$eq,$ne,$hasSome,$lt,$lte,$gt,$gteAllowed
lastUpdated$eq,$ne,$hasSome,$lt,$lte,$gt,$gteAllowed
paymentStatus$eq,$ne,$hasSome
archived$eq,$ne
number$eq,$ne,$hasSome,$lt,$lte,$gt,$gteAllowed
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

Copy
1
curl '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

Copy
1
curl '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

Copy
1
curl '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

Copy
1
curl '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'
Was this helpful?
Yes
No

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

  1. Go to your app in the Wix Developers Center.
  2. Go to the Webhooks tab in the side menu.
  3. Click + Add Webhook.
  4. Select an API Category > Wix eCommerce
  5. Find and select the Order Updated Webhook
  6. Add a Callback URL.
  7. 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:

  1. Install the EditThisCookie Chrome extension.
  2. 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

  1. Create a new Wix website with Wix Stores installed (testing this change only works on new sites).
  2. Refresh the Orders page.
  3. Navigate to an unfulfilled order in the dashboard.
  4. Click on the More Actions button in the top right corner.
  5. 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.

Was this helpful?
Yes
No

Orders Object

Properties
idstringRead-onlyformat GUID

Order ID (auto-generated upon order creation).


numberintegerRead-only

Order number displayed in the owner's store (auto-generated).


dateCreatedstringRead-onlyformat date-time

Order creation date and time.


buyerInfoobject

Buyer information.


currencystringformat CURRENCY

Currency used for the pricing of this order in ISO-4217 format.


weightUnitstring
3 enum supported values:
UNSPECIFIED_WEIGHT_UNITKGLB

Weight unit used in this store.


totalsobject

Totals for order's line items.


billingInfoobject

Billing information.


shippingInfoobject

Shipping information.


buyerNotestringmaxLength 1000

A note added by the buyer.


readbooleanRead-onlydeprecated

Deprecated.


archivedbooleanRead-only

Whether or not the order was archived.


paymentStatusstring
7 enum supported values:
UNSPECIFIED_PAYMENT_STATUSPENDINGNOT_PAIDPAIDPARTIALLY_REFUNDEDFULLY_REFUNDEDPARTIALLY_PAID

Current status of the payment.


fulfillmentStatusstringRead-only
4 enum supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED

Order's current fulfillment status (whether the order received a tracking number or was delivered/picked up).


lineItemsArray <LineItem>minItems 1maxItems 300

Line items ordered.


activitiesArray <Activity>Read-only

Log of updates related to the order.


invoiceInfoobject

Invoice information.


fulfillmentsArray <Fulfillment>Read-only

Order fulfillment information.


discountobject

Discount information.


customFieldobject

Custom field information.


cartIdstringformat GUID

Shopping cart ID.


buyerLanguagestringmaxLength 10

Language for communication with the buyer. Defaults to the site language. For a site that supports multiple languages, this is the language the buyer selected.


channelInfoobject

Information about the sales channel that submitted this order.


enteredByobjectRead-only

Identity of the order's initiator.


lastUpdatedstringRead-onlyformat date-time

Date and time of latest update.


subscriptionInfoobject

Subscription information.


numericIdnumberRead-only

Order’s unique numeric ID. Primarily used for sorting and filtering when crawling all orders.


refundsArray <Refund>Read-only

Refund information.

Was this helpful?
Yes
No

PostCreate Order

Deprecated

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 and billingInfo.paymentMethod parameters can only be passed when paymentStatus is PAID.
  • The billingInfo.address parameter is required unless channelInfo.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".
  • 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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/orders

Was this helpful?
Yes
No

PatchUpdate Order Email

Deprecated

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:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
PATCH
https://www.wixapis.com/stores/v2/orders/{orderId}/updateEmail

Was this helpful?
Yes
No

PutUpdate Order Shipping Address

Deprecated

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:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
PUT
https://www.wixapis.com/stores/v2/orders/{orderId}/updateShippingAddress

Was this helpful?
Yes
No

GetGet Order

Deprecated

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Endpoint
GET
https://www.wixapis.com/stores/v2/orders/{id}

Was this helpful?
Yes
No

PostQuery Orders

Deprecated

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/orders/query

Was this helpful?
Yes
No

PostCreate Fulfillment

Deprecated

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:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
POST
https://www.wixapis.com/stores/v2/orders/{orderId}/fulfillments

Was this helpful?
Yes
No

PutUpdate Fulfillment

Deprecated

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:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
PUT
https://www.wixapis.com/stores/v2/orders/{orderId}/fulfillments/{fulfillmentId}

Was this helpful?
Yes
No

DeleteDelete Fulfillment

Deprecated

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:
Manage Stores - all permissions
Manage Orders
Learn more about permission scopes.
Endpoint
DELETE
https://www.wixapis.com/stores/v2/orders/{orderId}/fulfillments/{fulfillmentId}

Was this helpful?
Yes
No

Order Created

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderIdstringformat GUID

Order ID (auto generated upon order creation)


numberinteger

ID displayed in the owner's store (auto generated)


dateCreatedstringformat date-time

Order creation date


buyerInfoobject

Customer information


currencystringmaxLength 3

Currency used for pricing in this store


weightUnitstring
3 enum supported values:
UNSPECIFIED_WEIGHT_UNITKGLB

Weight unit used in this store


totalsobject

Totals for order's line items


readboolean

Whether the order was read by the store owner


archivedboolean

Order archive status


paymentStatusstring
7 enum supported values:
UNSPECIFIED_PAYMENT_STATUSPENDINGNOT_PAIDPAIDPARTIALLY_REFUNDEDFULLY_REFUNDEDPARTIALLY_PAID

Order payment status


fulfillmentStatusstring
4 enum supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED

Order fulfillment status


Was this helpful?
Yes
No

Order Paid

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderobject

Paid order data.


Was this helpful?
Yes
No

Order Canceled

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderobjectRead-only

Canceled order data.


Was this helpful?
Yes
No

Order Refunded

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
refundIdstringRead-only

Refund ID.


orderobjectRead-only

Refunded order data.


Was this helpful?
Yes
No

Fulfillment Created

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderIdstringformat GUID

Order ID (auto generated upon order creation).


fulfillmentIdstringformat GUID

ID of the newly created fulfillment.


dateCreatedstringformat date-time

Fulfillment creation date and time.


buyerInfoobject

Buyer information.


fulfillmentStatusstring
4 enum supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED

Order fulfillment status.


trackingInfoobject

Fulfillment tracking information.


Was this helpful?
Yes
No

Fulfillment Updated

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:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderIdstringformat GUID

Order ID (auto generated upon order creation).


fulfillmentIdstringformat GUID

ID of the updated fulfillment.


trackingInfoobject

Fulfillment tracking information.


Was this helpful?
Yes
No

Fulfillment Deleted

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.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Stores - all permissions
Read Orders
Read Stores - all read permissions
Manage Orders
Learn more about permission scopes.
Event BodyEvent Body Event data is received as a JSON Web Token (JWT). It may be delayed. Be sure to verify the data was sent by Wix.
Event Data
orderIdstringformat GUID

Order ID (auto generated upon order creation).


fulfillmentIdstringformat GUID

ID of the deleted fulfillment.


fulfillmentStatusstring
4 enum supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED

Order fulfillment status.


Was this helpful?
Yes
No