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

Attributes
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