About the eCommerce Checkout API
The checkout is the second stage of the eCommerce purchase flow: cart; checkout; order.
A checkout holds information about items to be purchased, price and tax summaries, shipping and billing info, any applied discounts, and more.
The eCommerce Checkout API currently provides functionality for retrieving checkouts and listening to events when a checkout is created, updated, and marked as completed.
To assist in migration from the Stores to eCommerce APIs, please refer to the Stores Cart to eCommerce Checkout Conversion Table.
Future functionality includes creating and managing checkouts, as well as creating an order from a checkout.
Stores Cart to eCommerce Checkout Conversion Table
To help with migration to the eCommerce API, refer to the table below for differences between the Stores Cart and eCommerce Checkout objects.
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.
Stores Cart Object | eCommerce Checkout Object |
---|---|
id | - |
status | - |
weightUnit | weightUnit |
buyerNote | buyerNote |
currency.code | currency |
currency.symbol | For every price returned, we also provide the formatted price under checkout.priceSummary . |
convertedCurrency.code | conversionCurrency |
convertedCurrency.symbol | For every converted price returned, we also provide the formatted converted price under checkout.priceSummary . |
billingAddress.address | billingInfo.address - See address object conversion table for more details. |
billingAddress.contactDetails.firstName | billingInfo.contactDetails.firstName |
billingAddress.contactDetails.lastName | billingInfo.contactDetails.lastName |
billingAddress.contactDetails.phone | billingInfo.contactDetails.phone |
billingAddress.contactDetails.company | billingInfo.contactDetails.company |
billingAddress.contactDetails.vatId | billingInfo.contactDetails.vatId |
billingAddress.contactDetails.email | billingInfo.buyerInfo.email |
appliedCoupon.couponId | appliedDiscounts[i].coupon.id |
appliedCoupon.name | appliedDiscounts[i].coupon.name |
appliedCoupon.code | appliedDiscounts[i].coupon.code |
appliedCoupon.discountValue | appliedDiscounts[i].coupon.amount.amount |
appliedCoupon.convertedDiscountValue | appliedDiscounts[i].coupon.convertedAmount |
appliedCoupon.couponType | No longer returned. |
totals.subtotal | priceSummary.subtotal.amount |
totals.shipping | priceSummary.shipping.amount |
totals.tax | priceSummary.tax.amount |
totals.discount | priceSummary.discount.amount |
totals.total | priceSummary.total.amount |
totals.weight | lineItems[i].physicalProperties.weight X lineItems[i].quantity and so on. |
totals.quantity | lineItems[0].quantity + lineItems[1].quantity + lineItems[2].quantity and so on. |
convertedTotals.subtotal | priceSummary.subtotal.convertedAmount |
convertedTotals.shipping | priceSummary.shipping.convertedAmount |
convertedTotals.tax | priceSummary.tax.convertedAmount |
convertedTotals.discount | priceSummary.discount.convertedAmount |
convertedTotals.total | priceSummary.total.convertedAmount |
convertedTotals.weight | No weight conversion in checkout. Same value as cart.totals.weight . |
convertedTotals.quantity | Same value as cart.totals.quantity . |
shippingInfo.shippingRuleDetails.ruleId | ֿֿֿֿֿֿֿֿshippingInfo.region.id |
shippingInfo.shippingRuleDetails.optionId | ֿֿֿֿֿֿֿֿshippingInfo.selectedCarrierServiceOption.title |
shippingInfo.shippingRuleDetails.deliveryOption | ֿֿֿֿֿֿֿֿshippingInfo.selectedCarrierServiceOption.title |
shippingInfo.shippingRuleDetails.estimatedDeliveryTime | ֿֿֿֿֿֿֿֿshippingInfo.logistics.deliveryTime |
shippingInfo.pickupDetails.pickupAddress | shippingInfo.selectedCarrierServiceOption.logistics.pickupDetails.address - See address object conversion table for more details. |
shippingInfo.pickupDetails.buyerDetails.firstName | shippingInfo.shippingDestination.contactDetails.firstName |
shippingInfo.pickupDetails.buyerDetails.lastName | shippingInfo.shippingDestination.contactDetails.lastName |
shippingInfo.pickupDetails.buyerDetails.email | buyerInfo.email |
shippingInfo.pickupDetails.buyerDetails.phone | shippingInfo.shippingDestination.contactDetails.phone |
shippingInfo.pickupDetails.pickupInstructions | shippingInfo.logistics.instructions |
shippingInfo.shippingAddress.address | shippingInfo.shippingDestination.address - See address object conversion table for more details. |
shippingInfo.shippingAddress.contactDetails | shippingInfo.shippingDestination.contactDetails |
buyerInfo.id and buyerInfo.identityType: CONTACT | buyerInfo.contactId only. |
buyerInfo.id and buyerInfo.identityType: VISITOR | buyerInfo.visitorId only. |
buyerInfo.id and buyerInfo.identityType: MEMBER | buyerInfo.memberId only. |
buyerInfo.email | buyerInfo.email |
buyerInfo.phone | billingInfo.contactDetails.phone |
buyerInfo.firstName | billingInfo.contactDetails.firstName |
buyerInfo.lastName | billingInfo.contactDetails.lastName |
lineItems[i].id | lineItems[i].id - Note: this id is of type GUID. In the Stores Cart API, this id was of type Int32. |
lineItems[i].productId | lineItems[i].catalogReference.catalogItemId - See Stores Catalog eCommerce Integration for more information. |
lineItems[i].name | lineItems[i].productName.original |
lineItems[i].quantity | lineItems[i].quantity |
lineItems[i].weight | lineItems[i].physicalProperties.weight |
lineItems[i].sku | lineItems[i].physicalProperties.sku |
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].notes | lineItems[i].descriptionLines[i].plainText.original |
lineItems[i].customTextFields | lineItems[i].descriptionLines |
lineItems[i].mediaItem.mediaType | All line item media in the eCommerce Cart, Checkout, and Order APIs are image types. |
lineItems[i].mediaItem.url | lineItems[i].media.url |
lineItems[i].mediaItem.width | lineItems[i].media.width |
lineItems[i].mediaItem.height | lineItems[i].media.height |
lineItems[i].options | lineItems[i].catalogReference.options - See Stores Catalog eCommerce Integration for more information. |
lineItems[i].priceData.price | lineItems[i].price.amount |
lineItems[i].priceData.totalPrice | lineItems[i].price.amount X lineItems[i].quantity |
lineItems[i].convertedPriceData.price | lineItems[i].price.convertedAmount |
lineItems[i].convertedPriceData.totalPrice | lineItems[i].price.convertedAmount X lineItems[i].quantity |
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 Object | eCommerce Address Field Location | Change |
---|---|---|
address.city | address.city | |
address.email | buyerInfo.email | |
address.zipCode | address.postalCode | Field name |
address.country | address.country | |
address.addressLine1 | address.addressLine | Field name |
address.addressLine2 | address.addressLine2 | |
address.street | address.streetAddress | Field name |
address.subdivision | address.subdivision | |
address.fullName.firstName | contactDetails.firstName | Moved to contactDetails object |
address.fullName.lastName | contactDetails.lastName | Moved to contactDetails object |
address.phone | contactDetails.phone | Moved to contactDetails object |
address.company | contactDetails.company | Moved to contactDetails object |
address.vatId | contactDetails.vatId | Moved to contactDetails object |
Create and manage an eCommerce checkout
- "UNSPECIFIED": Unspecified sales channel. This value is not supported.
- "WEB": A web client.
- "POS": Point of sale solutions
- "EBAY": eBay
- "AMAZON": Amazon
- "WISH": Wish
- "WIX_INVOICES": Wix Invoices app in your dashboard
- "WIX_APP_STORE": Wix Owner app
- "BACKOFFICE_MERCHANT": Wix merchant backoffice
- "OTHER_PLATFORM": Other sales platform.
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates a checkout.
Note: For more information on what to pass to lineItems.catalogReference
, see eCommerce Integration in the Wix Stores Catalog API.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves a checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves the checkout page URL of a specified checkout.
By default, a checkoutUrl
generates for a checkout and directs to a standard Wix checkout page.
However, if overrideCheckoutUrl
has a value, it will replace and set the value of checkoutUrl
.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates a checkout.
Use this endpoint to update checkout fields such as billing and shipping info, or to add a coupon code or gift card.
To update a checkout's lineItems
, completed
status, or to remove coupons and gift cards, see these endpoints:
- Add to Checkout: Add line items to the checkout.
- Update Line Items Quantity: Update the quantity of one or more line items in the checkout.
- Remove Line Items: Remove a line item from the checkout.
- Mark Checkout As Completed: To update
completed
totrue
if the checkout was completed through a non-Wix orders or payments system. - Remove Coupon: To remove an applied coupon from the checkout.
- Remove Gift Card: To remove an applied gift card from the checkout.
Notes:
- If nothing is passed in the request, the call will fail.
- The
checkout.buyerInfo.email
may not be removed once it is set.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes the coupon from a specified checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes the gift card from a specified checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes the overrideCheckoutUrl
from a specified checkout.
When overrideCheckoutUrl
is removed, the checkoutUrl
will be set to the default, standard
Wix checkout page URL.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Adds line items to a checkout.
Note: For more information on what to pass to lineItems.catalogReference
, see eCommerce Integration in the Wix Stores Catalog API.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Removes specified line items from a checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Sets completed
to true
to mark a checkout as completed.
When an order is completed through Wix, the completed
field in the associated checkout object
will automatically be updated to true
. If an order is completed through a separate system,
use this endpoint to manually mark the checkout as completed.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Updates the quantity of one or more line items in a checkout.
This endpoint is only for updating the quantity of line items. To entirely remove a line item from the checkout, use Remove Line Items. To add a new line item to the checkout, use Add to Checkout.
This endpoint checks the amount of stock remaining for this line item. If the specified quantity
is greater than the remaining stock, then the quantity
returned in the response is the total amount
of remaining stock.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a checkout is created.
Permission Scopes
For app development, you must have one of the following permission scopes:This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Triggered when a checkout is updated.
Permission Scopes
For app development, you must have one of the following permission scopes: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 created from this checkout is successfully paid for or when a checkout is marked as completed.