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
No

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 ObjecteCommerce Checkout Object
id-
status-
weightUnitweightUnit
buyerNotebuyerNote
currency.codecurrency
currency.symbolFor every price returned, we also provide the formatted price under checkout.priceSummary.
convertedCurrency.codeconversionCurrency
convertedCurrency.symbolFor every converted price returned, we also provide the formatted converted price under checkout.priceSummary.
billingAddress.addressbillingInfo.address - See address object conversion table for more details.
billingAddress.contactDetails.firstNamebillingInfo.contactDetails.firstName
billingAddress.contactDetails.lastNamebillingInfo.contactDetails.lastName
billingAddress.contactDetails.phonebillingInfo.contactDetails.phone
billingAddress.contactDetails.companybillingInfo.contactDetails.company
billingAddress.contactDetails.vatIdbillingInfo.contactDetails.vatId
billingAddress.contactDetails.emailbillingInfo.buyerInfo.email
appliedCoupon.couponIdappliedDiscounts[i].coupon.id
appliedCoupon.nameappliedDiscounts[i].coupon.name
appliedCoupon.codeappliedDiscounts[i].coupon.code
appliedCoupon.discountValueappliedDiscounts[i].coupon.amount.amount
appliedCoupon.convertedDiscountValueappliedDiscounts[i].coupon.convertedAmount
appliedCoupon.couponTypeNo longer returned.
totals.subtotalpriceSummary.subtotal.amount
totals.shippingpriceSummary.shipping.amount
totals.taxpriceSummary.tax.amount
totals.discountpriceSummary.discount.amount
totals.totalpriceSummary.total.amount
totals.weightlineItems[i].physicalProperties.weight X lineItems[i].quantity and so on.
totals.quantitylineItems[0].quantity + lineItems[1].quantity + lineItems[2].quantity and so on.
convertedTotals.subtotalpriceSummary.subtotal.convertedAmount
convertedTotals.shippingpriceSummary.shipping.convertedAmount
convertedTotals.taxpriceSummary.tax.convertedAmount
convertedTotals.discountpriceSummary.discount.convertedAmount
convertedTotals.totalpriceSummary.total.convertedAmount
convertedTotals.weightNo weight conversion in checkout. Same value as cart.totals.weight.
convertedTotals.quantitySame 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.pickupAddressshippingInfo.selectedCarrierServiceOption.logistics.pickupDetails.address - See address object conversion table for more details.
shippingInfo.pickupDetails.buyerDetails.firstNameshippingInfo.shippingDestination.contactDetails.firstName
shippingInfo.pickupDetails.buyerDetails.lastNameshippingInfo.shippingDestination.contactDetails.lastName
shippingInfo.pickupDetails.buyerDetails.emailbuyerInfo.email
shippingInfo.pickupDetails.buyerDetails.phoneshippingInfo.shippingDestination.contactDetails.phone
shippingInfo.pickupDetails.pickupInstructionsshippingInfo.logistics.instructions
shippingInfo.shippingAddress.addressshippingInfo.shippingDestination.address - See address object conversion table for more details.
shippingInfo.shippingAddress.contactDetailsshippingInfo.shippingDestination.contactDetails
buyerInfo.id and buyerInfo.identityType: CONTACTbuyerInfo.contactId only.
buyerInfo.id and buyerInfo.identityType: VISITORbuyerInfo.visitorId only.
buyerInfo.id and buyerInfo.identityType: MEMBERbuyerInfo.memberId only.
buyerInfo.emailbuyerInfo.email
buyerInfo.phonebillingInfo.contactDetails.phone
buyerInfo.firstNamebillingInfo.contactDetails.firstName
buyerInfo.lastNamebillingInfo.contactDetails.lastName
lineItems[i].idlineItems[i].id - Note: this id is of type GUID. In the Stores Cart API, this id was of type Int32.
lineItems[i].productIdlineItems[i].catalogReference.catalogItemId - See Stores Catalog eCommerce Integration for more information.
lineItems[i].namelineItems[i].productName.original
lineItems[i].quantitylineItems[i].quantity
lineItems[i].weightlineItems[i].physicalProperties.weight
lineItems[i].skulineItems[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_ITEMlineItems[i].itemType.custom and lineItems[i].catalogReference is empty.
lineItems[i].noteslineItems[i].descriptionLines[i].plainText.original
lineItems[i].customTextFieldslineItems[i].descriptionLines
lineItems[i].mediaItem.mediaTypeAll line item media in the eCommerce Cart, Checkout, and Order APIs are image types.
lineItems[i].mediaItem.urllineItems[i].media.url
lineItems[i].mediaItem.widthlineItems[i].media.width
lineItems[i].mediaItem.heightlineItems[i].media.height
lineItems[i].optionslineItems[i].catalogReference.options - See Stores Catalog eCommerce Integration for more information.
lineItems[i].priceData.pricelineItems[i].price.amount
lineItems[i].priceData.totalPricelineItems[i].price.amount X lineItems[i].quantity
lineItems[i].convertedPriceData.pricelineItems[i].price.convertedAmount
lineItems[i].convertedPriceData.totalPricelineItems[i].price.convertedAmount X lineItems[i].quantity
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

Checkout Object

Create and manage an eCommerce checkout

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

priceSummaryobject
Calculated price summary for the checkout.

calculationErrorsobject
Errors when calculating totals.

giftCardobject
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 supported values:
UNSPECIFIED_WEIGHT_UNITKGLB
Weight measurement unit - defaults to site's weight unit.

taxSummaryobject
Tax summary.

currencystringRead-onlyformat CURRENCY
The currency used when submitting the order.

channelTypestringRead-only
12 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.

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

payNowobject
Minimal amount to pay in order to place the order.

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

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 defined when creating a checkout.
Was this helpful?
Yes
No

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Read eCommerce - all read permissions
Read Orders
Read Stores - all read permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Was this helpful?
Yes
No

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:
Manage Stores - all permissions
Read eCommerce - all read permissions
Read Orders
Read Stores - all read permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Was this helpful?
Yes
No

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:

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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:
Manage Stores - all permissions
Manage eCommerce - all permissions
Manage Orders
Learn more about permission scopes.Authorization header required - pass the OAuth Access Token

Syntax

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

Event Triggers

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

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.

Permissions

ECOM.READ_CHECKOUTS
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.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
No

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.

Permissions

ECOM.READ_CHECKOUTS
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.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
No

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.

Permissions

ECOM.READ_CHECKOUTS
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.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
No