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.
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 |
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
Note: Gift cards are supported through the Wix UI, though the SPI is not currently available. Learn more about Wix Gift Cards.
- "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.
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:Syntax
Retrieves a checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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:Syntax
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:Syntax
Removes the coupon from a specified checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
Removes the gift card from a specified checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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:Syntax
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:Syntax
Removes specified line items from a checkout.
Permission Scopes
For app development, you must have one of the following permission scopes:Syntax
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:Syntax
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:Syntax
Triggered when a checkout is created.
Event Body
Triggered when a checkout is updated.
Event Body
Triggered when an order created from this checkout is successfully paid for or when a checkout is marked as completed.