About the eCommerce Orders API

The eCommerce Orders API holds information about purchased items, price and tax summaries, shipping and billing info, any applied discounts, payment and fulfillment statuses, and more.

An order is the last stage of the eCommerce purchase flow: cart; checkout; order.

With the eCommerce Orders API you can:

Before you begin

If you are migrating from the Stores Orders API, please refer to the Stores to eCommerce Order Object Conversion Table.

Was this helpful?
Yes
No

Stores to eCommerce Order Object Conversion

To help with migration to the eCommerce Orders API, refer to the table below for field changes between the Stores order object and the eCommerce order object.

Note that some fields are accessible via other eCommerce APIs like Order Transactions or Order Fulfillments. In these cases, the way to access the info is described in the third column.

The address object used in the eCommerce APIs is slightly different to the one used in the Stores APIs. For more details, refer to the address object conversion table.

The eCommerce Order Updated event fires when a Stores order and/or an eCommerce order is updated. For more details on webhooks, refer to the Webhook Conversion Table below.

Fields marked with an asterisk (*) signify little to no change in semantics or access.

Order Object Conversion Table

Stores Order ObjecteCommerce Order ObjectNotes
id*id
number*number
dateCreatedcreatedDate
buyerInfo.idbuyerInfo.contactId & buyerInfo.memberId
buyerInfo.id and buyerInfo.identityType: "MEMBER"buyerInfo.memberId
buyerInfo.id and buyerInfo.identityType: "CONTACT"buyerInfo.contactId
buyerInfo.firstNamebillingInfo.contactDetails.firstName
buyerInfo.lastNamebillingInfo.contactDetails.lastName
buyerInfo.phonebillingInfo.contactDetails.phone
buyerInfo.email*buyerInfo.email
currency*currency
weightUnit*weightUnit
totals.subtotalpriceSummary.subtotal.amount
totals.shippingpriceSummary.shipping.amount
totals.taxpriceSummary.tax.amount
totals.discountpriceSummary.discount.amount
totals.totalpriceSummary.total.amount
totals.weightAn order's total weight is equal to (lineItems[0].physicalProperties.weight X lineItems[0].quantity) + (lineItems[1].physicalProperties.weight X lineItems[1].quantity) and so on.
totals.quantityAn order's total line item quantity is equal to lineItems[0].quantity + lineItems[1].quantity + lineItems[2].quantity and so on.
totals.refundAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
totals.giftCardAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.paymentMethodAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.paymentProviderTransactionIdAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.paymentGatewayTransactionIdAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.paidDateAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.refundableByPaymentProviderAvailable via the Order Transactions API.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.
billingInfo.address*billingInfo.addressAddress object conversion table.
shippingInfo.code*shippingInfo.code
shippingInfo.deliverByDateshippingInfo.logistics.deliverByDate
shippingInfo.deliveryOptionshippingInfo.title
shippingInfo.shippingRegionshippingInfo.region.name
shippingInfo.shippingDetails.addressshippingInfo.logistics.shippingDestination.addressAddress object conversion table.
shippingInfo.shipmentDetails.discountshippingInfo.cost.discount.amount
shippingInfo.shipmentDetails.taxshippingInfo.cost.taxDetails.totalTax.amount
shippingInfo.shipmentDetails.priceData.taxIncludedInPricetaxIncludedInPrices
shippingInfo.shipmentDetails.priceData.priceshippingInfo.cost.totalPriceAfterTax.amount
shippingInfo.pickupDetails.pickupAddressshippingInfo.logistics.pickupDetails.addressAddress object conversion table.
shippingInfo.pickupDetails.pickupInstructionsshippingInfo.logistics.instructions
shippingInfo.estimatedDeliveryTimeshippingInfo.logistics.deliveryTime
buyerNote*buyerNote
archived*archived
paymentStatus*paymentStatus
paymentStatus: PENDINGstatus: INITIALIZED
fulfillmentStatus*fulfillmentStatusFor more info, pass an order ID to the List Fulfillments For Single Order endpoint.
fulfillmentStatus: CANCELEDstatus: CANCELED
lineItems[i].indexlineItems[i].idWhile the lineItems[i].index in Stores Orders was an int32 type, the eCommerce Order's lineItems[i].id field is of type GUID.
lineItems[i].quantity*lineItems[i].quantity
lineItems[i].namelineItems[i].productName.original
lineItems[i].translatedNamelineItems[i].productName.translated
lineItems[i].productIdlineItems[i].catalogReference.catalogItemIdSee Stores Catalog eCommerce Integration for more information.
lineItems[i].lineItemType: "PHYSICAL"lineItems[i].itemType.preset: "PHYSICAL"
lineItems[i].lineItemType: "DIGITAL"lineItems[i].itemType.preset: "DIGITAL"
lineItems[i].lineItemType: "CUSTOM_AMOUNT_ITEM"lineItems[i].itemType.custom and lineItems[i].catalogReference is empty.
lineItems[i].optionslineItems[i].descriptionLines
lineItems[i].customTextFieldslineItems[i].catalogReference.optionsWithin the catalogReference.options look for the customTextFields key.
lineItems[i].weightlineItems[i].physicalProperties.weight
lineItems[i].mediaItem.urllineItems[i].image.url
lineItems[i].mediaItem.heightlineItems[i].image.height
lineItems[i].mediaItem.widthlineItems[i].image.width
lineItems[i].mediaItem.idlineItems[i].image.id
lineItems[i].mediaItem.altTextlineItems[i].image.altText
lineItems[i].skulineItems[i].physicalProperties.sku
lineItems[i].noteslineItems[i].descriptionLines[i].plainText.original
lineItems[i].variantIdlineItems[i].catalogReference.optionsSee Stores Catalog eCommerce Integration for more information.
lineItems[i].fulfillerId*lineItems[i].fulfillerId
lineItems[i].discountlineItems[i].totalDiscount.amount
lineItems[i].taxlineItems[i].taxDetails.totalTax.amount
lineItems[i].priceData.taxIncludedInPricetaxIncludedInPrices
lineItems[i].priceData.pricelineItems[i].price.amount
lineItems[i].priceData.totalPricelineItems[i].totalPriceAfterTax.amount
activities[i].type*activities[i].type
activities[i].TRACKING_LINK_WAS_SETactivities[i].TRACKING_LINK_SET
activities[i].INVOICE_WAS_SETactivities[i].INVOICE_ADDED
activities[i].INVOICE_WAS_SENTactivities[i].INVOICE_SENT
activities[i].authoractivities[i].authorEmail
activities[i].messageactivities[i].merchantComment.messageIf activities.type = "MERCHANT_COMMENT"
activities[i].timestampactivities[i].createdDate
invoiceInfoNot available in eCommerce order object.Currently, this information is held in the Stores order object. Pass order.id to the Stores Get Order endpoint.
fulfillmentsNot available in eCommerce order object.For more info, pass an order ID to the List Fulfillments For Single Order endpoint.
discount.appliedCoupon.couponIdappliedDiscounts[i].coupon.idSearch the appliedDiscounts array for the coupon field; couponId is coupon.id
discount.appliedCoupon.nameappliedDiscounts[i].coupon.nameSearch the appliedDiscounts array for the coupon field; name is coupon.name
discount.appliedCoupon.codeappliedDiscounts[i].coupon.codeSearch the appliedDiscounts array for the coupon field; code is coupon.code
customField.valuecustomFields[i].value.stringValueNote: customFields is an array
customField.titlecustomFields[i].title
customField.translatedTitlecustomFields[i].translatedTitle
cartIdNot returned in the eCommerce order object.Replaced by checkoutId
buyerLanguage*buyerLanguage
channelInfo.type*channelInfo.type
channelInfo.externalOrderId*channelInfo.externalOrderId
channelInfo.externalOrderUrl*channelInfo.externalOrderUrl
enteredBy.id and enteredBy.identityType: "MEMBER"createdBy.memberId
enteredBy.id and enteredBy.identityType: "USER"createdBy.userId
enteredBy.id and enteredBy.identityType: "APP"createdBy.appId
enteredBy.id and enteredBy.identityType: "CONTACT"createdBy.visitorIdPreviously, for a buyer that is not logged in, CONTACT type and ID were returned. in the eCommerce API, visitorId is returned. Note: the ID itself will also be different.
lastUpdatedupdatedDate
numericId-Removed due to added cursor paging functionality
refundsNot available in eCommerce order object.Pass the order ID to the List Transactions For Single Order endpoint to retrieve this info.

*Fields marked with an asterisk signify little to no change in semantics or access.

Webhook Conversion Table

The following list shows Stores Orders webhooks and the eCommerce Orders webhooks that are triggered at the same time:

Stores Orders APIeCommerce Orders API
Order Paid WebhookPayment Status Updated Webhook sent with order.paymentStatus = PAID
Order Created WebhookOrder Approved Webhook
Order Canceled WebhookOrder Canceled Webhook

The structure of the webhook payload has been updated. For example, the order ID is provided both at the top level as entityId and as order.id within the payload itself. The table below describes where to find the order ID or order entity in the new webhook payloads:

Stores WebhookseCommerce Webhooks
Order ID - order.id / orderIdAll order webhook payloads - entityId
Order Created - the payload itself is the orderOrder Approved - actionEvent.body.order
Order Paid/Canceled/Refunded - orderOrder Canceled/Approved - actionEvent.body.order
-Order Updated - updatedEvent.currentEntity
Was this helpful?
Yes
No

Address Object Conversion Table

The eCommerce APIs use a different address object. Notably, fields related to contact information have been moved to an adjacent contactDetails object (for example, in order.shippingInfo).

To help with conversion and migration, refer to the table below to check which fields have changed and how.

Note: in the eCommerce API, the buyer's email is only held in the buyerInfo field in the eCommerce Order object.

Previous Address ObjecteCommerce Address Field LocationChange
address.cityaddress.city
address.emailbuyerInfo.email
address.zipCodeaddress.postalCodeField name
address.countryaddress.country
address.addressLine1address.addressLineField name
address.addressLine2address.addressLine2
address.streetaddress.streetAddressField name
address.subdivisionaddress.subdivision
address.fullName.firstNamecontactDetails.firstNameMoved to contactDetails object
address.fullName.lastNamecontactDetails.lastNameMoved to contactDetails object
address.phonecontactDetails.phoneMoved to contactDetails object
address.companycontactDetails.companyMoved to contactDetails object
address.vatIdcontactDetails.vatIdMoved to contactDetails object
Was this helpful?
Yes
No

Order Object

Create and manage eCommerce orders

Attributes
idstringRead-onlyformat GUID
Order ID.

numbernumberRead-only
Order number displayed in the site owner's business manager (auto-generated).

createdDatestringformat date-time
Date and time the order was created in ISO-8601 format.

updatedDatestringRead-onlyformat date-time
Date and time the order was last updated in ISO-8601 format.

lineItemsArray <OrderLineItem>minItems 1maxItems 300
Order line items.

buyerInfoobject
Buyer information.

paymentStatusstring
7 supported values:
UNSPECIFIEDNOT_PAIDPAIDPARTIALLY_REFUNDEDFULLY_REFUNDEDPENDINGPARTIALLY_PAID
Order payment status.
  • NOT_PAID - This can be an order made online, but not yet paid. In such cases order.status will be INITIALIZED.
  • This status also applies when an offline order needs to be manually marked as paid. In such cases order.status will be APPROVED.
  • PAID - All payments associated with this order are paid. For online payments: payment.regularPaymentDetails.status: APPROVED. For gift cards: payment.giftCardPaymentDetails.voided: false.
  • PARTIALLY_REFUNDED - Order was refunded, but refund amount is less than order total price.
  • FULLY_REFUNDED - Order fully refunded. Refund amount equals total price.
  • PENDING - Payments received but not yet confirmed by the payment provider.
  • PARTIALLY_PAID - At least one payment was received and approved, covering less than total price amount.

fulfillmentStatusstringRead-only
3 supported values:
NOT_FULFILLEDFULFILLEDPARTIALLY_FULFILLED
Order fulfillment status.

buyerLanguagestring
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.

weightUnitstring
3 supported values:
UNSPECIFIED_WEIGHT_UNITKGLB
Weight measurement unit - defaults to site's weight unit.

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

taxIncludedInPricesboolean
Whether tax is included in line item prices.

siteLanguagestringRead-only
Site language in which original values are shown.

priceSummaryobject
Order price summary.

billingInfoobject
Billing address and contact details.

shippingInfoobject
Shipping info and selected shipping option details.

buyerNotestringmaxLength 1000
Buyer note left by the customer.

statusstring
3 supported values:
INITIALIZEDAPPROVEDCANCELED
Order status.
  • INITIALIZED - Order was created, but not yet approved or declined.
  • APPROVED - Order was approved. This happens when either the online payment succeeded or the order is an offline order. Once an order is approved, many side effects are triggered. For example, holding of stock in the inventory and sending of notification emails.
  • CANCELED - Order was canceled by the user.

archivedbooleanRead-only
Whether order is archived.

taxSummaryobject
Tax summary.

appliedDiscountsArray <AppliedDiscount>
Applied discounts.

activitiesArray <Activity>Read-onlymaxItems 1000
Order activities.

attributionSourcestring
2 supported values:
UNSPECIFIEDFACEBOOK_ADS
Order attribution source.

createdByobject
ID of the order's initiator.

channelInfoobject
Information about the sales channel that submitted this order.

seenByAHumanbooleanRead-only
Whether a human has seen the order. Set when an order is clicked on in the Business Manager.

checkoutIdstringformat GUID
Checkout ID.

customFieldsArray <CustomField>
Custom fields.

additionalFeesArray <AdditionalFee>maxItems 100
Additional fees applied to the order.

purchaseFlowIdstringformat GUID
Persistent ID that correlates between the various eCommerce elements: cart, checkout, and order.
Was this helpful?
Yes
No

GetGet Order

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Retrieves an order with the provided ID.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage eCommerce - all permissions
Read eCommerce - all read permissions
Read Stores - all read permissions
Manage Orders
Read Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

GET
https://www.wixapis.com/ecom/v1/orders/{id}

Was this helpful?
Yes
No

PostCancel Order

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Cancels an order. The order.status field changes to CANCELED.

Permission Scopes

For app development, you must have one of the following permission scopes:
Manage eCommerce - all permissions
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

POST
https://www.wixapis.com/ecom/v1/orders/{id}/cancel

Event Triggers

This method triggers the following events:
Was this helpful?
Yes
No

Order Updated

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an order is updated.

Permissions

ECOM.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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecom.v1.order.

slugstring
Event name. Expected updated.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

updatedEventobject
Event information.
Was this helpful?
Yes
No

Order Canceled

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an order is canceled.

Permissions

ECOM.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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecom.v1.order.

slugstring
Event name. Expected canceled.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No

Order Approved

Developer Preview - This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.

Triggered when an order is created and its status is updated to "APPROVED".

Permissions

ECOM.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
idstring
Unique event ID. Allows clients to ignore duplicate webhooks.

entityFqdnstring
Fully qualified domain name of the entity associated with the event. Expected wix.ecom.v1.order.

slugstring
Event name. Expected approved.

entityIdstring
ID of the entity associated with the event.

eventTimestringformat date-time
Event timestamp.

triggeredByAnonymizeRequestboolean
Whether the event was triggered as a result of a privacy regulation application (for example, GDPR).

originatedFromstring
If present, indicates the action that triggered the event.

actionEventobject
Event information.
Was this helpful?
Yes
No