Setup

To use the Checkout API, install the @wix/ecom package using npm or Yarn:

Copy
1
npm install @wix/ecom

or

Copy
1
yarn add @wix/ecom

Then import { checkout } from @wix/ecom:

Copy
1
import { checkout } from '@wix/ecom'
Was this helpful?
Yes
No
addToCheckout( )

Adds catalog line items and/or custom line items to a checkout.

The addToCheckout() function returns a Promise that resolves to the updated checkout when the specified items have been added.

Note: When adding catalog items, options.lineItems.catalogReference is required.

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.
Copy
function addToCheckout(_id: string, options: AddToCheckoutOptions): Promise<AddToCheckoutResponse>
Method Parameters
_idstringRequired

Checkout ID.

optionsAddToCheckoutOptions

Items to be added to checkout.

Returns
Return Type:Promise<AddToCheckoutResponse>
Was this helpful?
Yes
No
createCheckout( )

Creates a checkout.

The createCheckout() function returns a Promise that resolves to the new checkout when it's created.

Notes:

  • Checkout must include at least 1 item in the options.lineItems array.
  • options.channelType is required.
  • If _id for options.lineItems is added, make sure that each _id is unique.
  • If options.checkoutInfo.customFields are added, then options.checkoutInfo.customFields.value is required.

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.
Copy
function createCheckout(options: CreateCheckoutOptions): Promise<Checkout>
Method Parameters
optionsCreateCheckoutOptions

Checkout creation options.

Returns
Return Type:Promise<Checkout>
Was this helpful?
Yes
No
createOrder( )
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 an order from a specified checkout.

The createOrder() function returns a Promise that resolves to the new order's ID and paymentGatewayOrderID when the order is created. Pass the paymentGatewayOrderId as the paymentId param to the startPayment() function to allow a customer to pay for their order.

Note: The following requirements must be met for an order to be created from a checkout.

  • A checkout cannot have calculation errors. Pass the checkout._id to Get Checkout and take a look at the calculationErrors field.
  • A checkout must have at least 1 line item.
  • All of the line Items have an availability.status of "AVAILABLE" or "PARTIALLY_AVAILABLE".
  • If there is a payment to be made, meaning that priceSummary.total is greater than 0, the billingInfo.address field must be provided.
  • When a checkout has line items to be shipped, the shippingInfo.shippingDestination.address and shippingInfo.selectedCarrierServiceOption fields must be provided.
  • When a checkout has line items for pickup, the shippingInfo.selectedCarrierServiceOption.logistics.pickupDetails field must be provided.

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.
Copy
function createOrder(_id: string): Promise<CreateOrderResponse>
Method Parameters
_idstringRequired

Checkout ID.

Returns
Return Type:Promise<CreateOrderResponse>
Was this helpful?
Yes
No
getCheckout( )

Retrieves a checkout.

The getCheckout() function returns a Promise that resolves when the specified checkout is retrieved.

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.
Copy
function getCheckout(_id: string): Promise<Checkout>
Method Parameters
_idstringRequired

Checkout ID.

Returns
Return Type:Promise<Checkout>
Was this helpful?
Yes
No
getCheckoutUrl( )
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.
Copy
function getCheckoutUrl(_id: string): Promise<GetCheckoutURLResponse>
Method Parameters
_idstringRequired

Checkout ID.

Returns
Return Type:Promise<GetCheckoutURLResponse>
Was this helpful?
Yes
No
markCheckoutAsCompleted( )

Marks a checkout as completed - checkout.complete boolean is set to true.

The markCheckoutAsCompleted() function returns a Promise that resolves when the specified checkout is marked 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.
Copy
function markCheckoutAsCompleted(_id: string): Promise<void>
Method Parameters
_idstringRequired

Checkout ID.

Was this helpful?
Yes
No
removeCoupon( )

Removes the coupon from a specified checkout.

The removeCoupon() function returns a Promise that resolves to the updated checkout when the coupon is removed from the specified checkout.

Note: A checkout can only hold 1 coupon.

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.
Copy
function removeCoupon(_id: string): Promise<RemoveCouponResponse>
Method Parameters
_idstringRequired

ID of the checkout to remove the coupon from.

Returns
Return Type:Promise<RemoveCouponResponse>
Was this helpful?
Yes
No
removeGiftCard( )

Removes the gift card from a specified checkout.

The removeGiftCard() function returns a Promise that resolves to the updated checkout when the gift card is removed from the specified checkout.

Note: A checkout can only hold 1 gift card.

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.
Copy
function removeGiftCard(_id: string): Promise<RemoveGiftCardResponse>
Method Parameters
_idstringRequired

ID of the checkout to remove the gift card from.

Returns
Return Type:Promise<RemoveGiftCardResponse>
Was this helpful?
Yes
No
removeLineItems( )

Removes line items from the specified checkout.

The removeLineItems() function returns a Promise that resolves to the updated checkout when the line items are removed from the 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.
Copy
function removeLineItems(_id: string, lineItemIds: Array<string>): Promise<RemoveLineItemsResponse>
Method Parameters
_idstringRequired

ID of the checkout to remove line items from.

lineItemIdsArray<string>Required

IDs of the line items to be removed. To find the IDs of the checkout line items you'd like to remove, pass the checkout._id to getCheckout() and look for the IDs under lineItems and/or customLineItems.

Returns
Return Type:Promise<RemoveLineItemsResponse>
Was this helpful?
Yes
No
removeOverrideCheckoutUrl( )
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.
Copy
function removeOverrideCheckoutUrl(_id: string): Promise<RemoveOverrideCheckoutUrlResponse>
Method Parameters
_idstringRequired

ID of the checkout to remove the override checkout url from.

Returns
Return Type:Promise<RemoveOverrideCheckoutUrlResponse>
Was this helpful?
Yes
No
updateCheckout( )

Updates a checkout.

The updateCheckout() function returns a Promise that resolves to the updated checkout when the specified properties are updated.

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.
Copy
function updateCheckout(_id: string, checkout: UpdateCheckout, options: UpdateCheckoutOptions): Promise<Checkout>
Method Parameters
_idstringRequired

Checkout ID.

checkoutUpdateCheckoutRequired
optionsUpdateCheckoutOptions

Checkout update options.

Returns
Return Type:Promise<Checkout>
Was this helpful?
Yes
No
updateLineItemsQuantity( )

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 removeLineItems(). To add a new line item to the checkout, use addToCheckout().

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.
Copy
function updateLineItemsQuantity(_id: string, lineItems: Array<LineItemQuantityUpdate>): Promise<UpdateLineItemsQuantityResponse>
Method Parameters
_idstringRequired

Checkout ID.

lineItemsArray<LineItemQuantityUpdate>Required

Line item info to update.

Returns
Return Type:Promise<UpdateLineItemsQuantityResponse>
Was this helpful?
Yes
No