Orders Service

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 Code
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 Code
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 Code
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 Code
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
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 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-only
Deprecated.
archivedbooleanRead-only
Whether or not the order was archived.
paymentStatusstring
7 supported values:
UNSPECIFIED_PAYMENT_STATUSPENDINGNOT_PAIDPAIDPARTIALLY_REFUNDEDFULLY_REFUNDEDPARTIALLY_PAID
Current status of the payment.
fulfillmentStatusstringRead-only
4 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.
enteredByobject
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

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 eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
PatchUpdate Order Email

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 Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
PutUpdate Order Shipping Address

Updates the shipping address of a specified order.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
GetGet Order

Returns an order with the provided ID

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Read Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
PostQuery Orders

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 Orders
Read Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
PostCreate Fulfillment

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 Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
PutUpdate Fulfillment

Updates an existing fulfillment

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
DeleteDelete Fulfillment

Deletes an existing fulfillment

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token
Was this helpful?
Yes
No
Order Created

Triggered when an order is created.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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 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 supported values:
UNSPECIFIED_PAYMENT_STATUSPENDINGNOT_PAIDPAIDPARTIALLY_REFUNDEDFULLY_REFUNDEDPARTIALLY_PAID
Order payment status
fulfillmentStatusstring
4 supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED
Order fulfillment status
Was this helpful?
Yes
No
Order Paid

Triggered when an order is paid.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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

Triggered when an order is canceled.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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
Canceled order data.
Was this helpful?
Yes
No
Order Refunded

Triggered when an order is refunded.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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.
orderobject
Refunded order data.
Was this helpful?
Yes
No
Fulfillment Created

Triggered when a tracking number is added to a fulfillment.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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 supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED
Order fulfillment status.
trackingInfoobject
Fulfillment tracking information.
Was this helpful?
Yes
No
Fulfillment Updated

Triggered when a fulfillment is updated.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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

Triggered when a fulfillment is deleted.

Permissions

WIX_STORES.READ_ORDERS
Learn more about permissions.

Event Body

Event 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 supported values:
NOT_FULFILLEDFULFILLEDCANCELEDPARTIALLY_FULFILLED
Order fulfillment status.
Was this helpful?
Yes
No