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.

Was this helpful?

Yes

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`

Was this helpful?

Yes

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

Was this helpful?

Yes

Checkout Object

Create and manage an eCommerce checkout

Properties

idstringRead-onlyformat GUID

Checkout ID.

lineItemsArray <LineItem>Read-onlyminItems 1maxItems 300

Line items. Max: 300 items

billingInfoobject

Billing information.

shippingInfoobject

Shipping information.

buyerNotestringmaxLength 1000

Buyer note left by the customer.

buyerInfoobject

Buyer information.

conversionCurrencystringRead-onlyformat CURRENCY

All converted prices are displayed in this currency in three-letter ISO-4217 alphabetic format.

priceSummaryobjectRead-only

Calculated price summary for the checkout.

calculationErrorsobjectRead-only

Errors when calculating totals.

giftCardobjectRead-only

Applied gift card details.

Note: Gift cards are supported through the Wix UI, though the SPI is not currently available. Learn more about Wix Gift Cards.

appliedDiscountsArray <AppliedDiscount>Read-only

Applied discounts.

customFieldsArray <CustomField>

Custom fields.

weightUnitstringRead-only

3 enum supported values:

UNSPECIFIED_WEIGHT_UNITKGLB

Weight measurement unit - defaults to site's weight unit.

taxSummaryobjectRead-only

Tax summary.

currencystringRead-onlyformat CURRENCY

The currency used when submitting the order.

channelTypestringRead-only

12 enum supported values:

UNSPECIFIEDWEBPOSEBAYAMAZONOTHER_PLATFORMWIX_APP_STOREWIX_INVOICESBACKOFFICE_MERCHANTWISHCLASS_PASSGLOBAL_E

Sales channel that submitted the order.

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

siteLanguagestringRead-only

Site language in which original values are shown.

buyerLanguagestringRead-only

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.

completedbooleanRead-only

Whether an order was successfully created from this checkout. For an order to be successful, it must be successfully paid for (unless the total is 0).

taxIncludedInPricebooleanRead-only

Whether tax is included in line item prices.

createdByobjectRead-only

ID of the checkout's initiator.

createdDatestringRead-onlyformat date-time

Date and time the checkout was created.

updatedDatestringRead-onlyformat date-time

Date and time the checkout was updated.

payNowobjectRead-only

Minimal amount to pay in order to place the order.

payLaterobjectRead-only

Remaining amount for the order to be fully paid.

membershipOptionsobject

Memberships to apply when creating the order.

additionalFeesArray <AdditionalFee>maxItems 100

Additional Fees.

cartIdstringformat GUID

Cart ID that this checkout was created from. Empty if this checkout wasn't created from a cart.

violationsArray <Violation>Read-only

List of validation violations raised by the Validations SPI.

extendedFieldsobject

Custom field data for the checkout object. Extended fields must be configured in the Wix Dev Center before they can be accessed with API calls.

purchaseFlowIdstringRead-onlyformat GUID

Persistent ID that correlates between the various eCommerce elements: cart, checkout, and order.

customSettingsobject

Additional settings for customization of the checkout process. Custom settings can only be set when creating a checkout.

Was this helpful?

Yes

PostCreate Checkout

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts

Event TriggersThis method triggers the following events:

Checkout Created

Was this helpful?

Yes

GetGet Checkout

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 a checkout.

Permission Scopes

For app development, you must have one of the following permission scopes:

Learn more about permission scopes.

Endpoint

GET

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

Was this helpful?

Yes

GetGet Checkout URL

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 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:

Learn more about permission scopes.

Endpoint

GET

https://www.wixapis.com/ecom/v1/checkouts/{id}/checkout-url

Was this helpful?

Yes

PatchUpdate Checkout

Developer Preview

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 to true 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:

Learn more about permission scopes.

Endpoint

PATCH

https://www.wixapis.com/ecom/v1/checkouts/{checkout.id}

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostRemove Coupon

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/remove-coupon

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostRemove Gift Card

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/remove-gift-card

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostRemove Override Checkout Url

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/remove-override-checkout-url

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostAdd To Checkout

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/add-to-checkout

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostRemove Line Items

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/remove-line-items

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

PostMark Checkout As Completed

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/mark-as-completed

Event TriggersThis method triggers the following events:

Checkout Updated Checkout Completed

Was this helpful?

Yes

PostUpdate Line Items Quantity

Developer Preview

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:

Learn more about permission scopes.

Endpoint

POST

https://www.wixapis.com/ecom/v1/checkouts/{id}/update-line-items-quantity

Event TriggersThis method triggers the following events:

Checkout Updated

Was this helpful?

Yes

Checkout Created

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 a checkout is created.

Permission Scopes

For app development, you must have one of the following permission scopes:

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

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

slugstring

Event name. Expected created.

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.

createdEventobject

Event information.

Was this helpful?

Yes

Checkout 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 a checkout is updated.

Permission Scopes

For app development, you must have one of the following permission scopes:

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

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

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

Checkout Marked As Completed

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 created from this checkout is successfully paid for or when a checkout is marked as completed.

Permission Scopes

For app development, you must have one of the following permission scopes:

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

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

slugstring

Event name. Expected completed.

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