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

Did this help?

Cart Object

Create and manage an eCommerce cart

Properties

idstringformat GUID

Cart ID.

lineItemsArray <LineItem>Read-onlyminItems 1maxItems 300

Line items.

buyerNotestringmaxLength 1000

Note left by the buyer/customer.

buyerInfoBuyerInfo

Buyer information.

currencystringRead-onlyformat CURRENCY

Currency used for pricing.

conversionCurrencystringRead-onlyformat CURRENCY

Currency code used for all the converted prices that are returned. For a site that supports multiple currencies, this is the currency the buyer selected.

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.

siteLanguagestringRead-only

Site language in which original values are displayed.

taxIncludedInPricesbooleanRead-only

Whether tax is included in line item prices.

weightUnitstringRead-only

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

checkoutIdstringRead-onlyformat GUID

ID of the checkout that originated from this cart.

appliedDiscountsArray <CartDiscount>Read-only

Cart discounts.

createdDatestringRead-onlyformat date-time

Date and time the cart was created.

updatedDatestringRead-onlyformat date-time

Date and time the cart was updated.

contactInfoContactInfo

Contact info.

overrideCheckoutUrlstringmaxLength 1000

overrideCheckoutUrl allows the flexibility to redirect customers to a customized checkout page.

This field overrides the checkoutUrl in a cart or checkout. checkoutUrl is used in the Abandoned Checkout API to send customers back to their checkouts. By default, a checkoutUrl generates for a checkout and directs to a standard Wix checkout page. When overrideCheckoutUrl has a value, it will replace and set the value of checkoutUrl.

purchaseFlowIdstringRead-onlyformat GUID

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

selectedShippingOptionSelectedShippingOption

Selected shipping option.

Object Sample Shown:Cart

JSON


{
  "cart": {
    "id": "b7b79cdb-5ff5-4ce8-8b64-0e28b1ea7a95",
    "lineItems": [
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "quantity": 1,
        "catalogReference": {
          "catalogItemId": "df19c1f7-07d8-a265-42f8-e8dfa824cc6e",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
          "options": {
            "variantId": "e62fee23-7878-437a-bf0e-292f17d11cb5"
          }
        },
        "productName": {
          "original": "Shoe",
          "translated": "Shoe"
        },
        "url": {
          "relativePath": "/product-page/shoe",
          "url": "https://example.wixsite.com"
        },
        "price": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "fullPrice": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "priceBeforeDiscounts": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "descriptionLines": [
          {
            "name": {
              "original": "Color",
              "translated": "Color"
            },
            "colorInfo": {
              "original": "Black",
              "translated": "Black",
              "code": "#000"
            }
          }
        ],
        "image": {
          "id": "3c76e2_bf235c38610f4d2a905db71095b351cf~mv2.jpg",
          "url": "https://static.wixstatic.com/media/3c76e2_bf235c38610f4d2a905db71095b351cf~mv2.jpg",
          "height": 1000,
          "width": 1000
        },
        "availability": {
          "status": "AVAILABLE",
          "quantityAvailable": 30
        },
        "physicalProperties": {
          "sku": "364215376135191",
          "shippable": true
        },
        "couponScopes": [
          {
            "namespace": "stores",
            "group": {
              "name": "collection",
              "entityId": "00000000-000000-000000-000000000001"
            }
          },
          {
            "namespace": "stores",
            "group": {
              "name": "product",
              "entityId": "df19c1f7-07d8-a265-42f8-e8dfa824cc6e"
            }
          }
        ],
        "itemType": {
          "preset": "PHYSICAL"
        },
        "paymentOption": "FULL_PAYMENT_ONLINE"
      },
      {
        "id": "00000000-0000-0000-0000-000000000002",
        "quantity": 1,
        "catalogReference": {
          "catalogItemId": "c8539b66-7a44-fe18-affc-afec4be8562a",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
        },
        "productName": {
          "original": "Shirt",
          "translated": "Shirt"
        },
        "url": {
          "relativePath": "/product-page/shirt",
          "url": "https://example.wixsite.com"
        },
        "price": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "fullPrice": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "priceBeforeDiscounts": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "descriptionLines": [],
        "image": {
          "id": "3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "url": "https://static.wixstatic.com/media/3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "height": 1000,
          "width": 1000
        },
        "availability": {
          "status": "AVAILABLE"
        },
        "physicalProperties": {
          "sku": "364115376135191",
          "shippable": true
        },
        "couponScopes": [
          {
            "namespace": "stores",
            "group": {
              "name": "collection",
              "entityId": "00000000-000000-000000-000000000001"
            }
          },
          {
            "namespace": "stores",
            "group": {
              "name": "product",
              "entityId": "c8539b66-7a44-fe18-affc-afec4be8562a"
            }
          }
        ],
        "itemType": {
          "preset": "PHYSICAL"
        },
        "paymentOption": "FULL_PAYMENT_ONLINE"
      }
    ],
    "buyerInfo": {
      "userId": "c43190d2-eea3-493e-b6e8-f146850c6873"
    },
    "currency": "USD",
    "conversionCurrency": "USD",
    "buyerLanguage": "en",
    "siteLanguage": "en",
    "taxIncludedInPrices": false,
    "weightUnit": "KG",
    "subtotal": {
      "amount": "95",
      "convertedAmount": "95",
      "formattedAmount": "$95.00",
      "formattedConvertedAmount": "$95.00"
    },
    "appliedDiscounts": [
      {
        "coupon": {
          "id": "fbb94b06-7447-4161-9c48-59bfcdc39e77",
          "code": "SUMMERSALE10"
        }
      }
    ],
    "inSync": false,
    "createdDate": "2022-12-12T08:53:43.520Z",
    "updatedDate": "2022-12-12T09:23:36.598Z"
  }
}

Did this help?

GET

Get Current Cart

Retrieves the current site visitor's cart.

Note: This endpoint requires visitor or member authentication.

Permissions

Learn more about app permissions.

Endpoint

GET

https://www.wixapis.com/ecom/v1/carts/current

Request

This endpoint does not take any parameters.

Response Object

cartCart

Current session's active cart.

Example shown:Get the current site visitor's cart

Request

cURL


curl -X GET \
  'https://www.wixapis.com/ecom/v1/carts/current' \
  -H 'Authorization: <AUTH>'

Response

JSON


{
  "cart": {
    "id": "b7b79cdb-5ff5-4ce8-8b64-0e28b1ea7a95",
    "lineItems": [
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "quantity": 1,
        "catalogReference": {
          "catalogItemId": "df19c1f7-07d8-a265-42f8-e8dfa824cc6e",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e",
          "options": {
            "variantId": "e62fee23-7878-437a-bf0e-292f17d11cb5"
          }
        },
        "productName": {
          "original": "Shoe",
          "translated": "Shoe"
        },
        "url": {
          "relativePath": "/product-page/shoe",
          "url": "https://example.wixsite.com"
        },
        "price": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "fullPrice": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "priceBeforeDiscounts": {
          "amount": "85",
          "convertedAmount": "85",
          "formattedAmount": "$85.00",
          "formattedConvertedAmount": "$85.00"
        },
        "descriptionLines": [
          {
            "name": {
              "original": "Color",
              "translated": "Color"
            },
            "colorInfo": {
              "original": "Black",
              "translated": "Black",
              "code": "#000"
            }
          }
        ],
        "image": {
          "id": "3c76e2_bf235c38610f4d2a905db71095b351cf~mv2.jpg",
          "url": "https://static.wixstatic.com/media/3c76e2_bf235c38610f4d2a905db71095b351cf~mv2.jpg",
          "height": 1000,
          "width": 1000
        },
        "availability": {
          "status": "AVAILABLE",
          "quantityAvailable": 30
        },
        "physicalProperties": {
          "sku": "364215376135191",
          "shippable": true
        },
        "couponScopes": [
          {
            "namespace": "stores",
            "group": {
              "name": "collection",
              "entityId": "00000000-000000-000000-000000000001"
            }
          },
          {
            "namespace": "stores",
            "group": {
              "name": "product",
              "entityId": "df19c1f7-07d8-a265-42f8-e8dfa824cc6e"
            }
          }
        ],
        "itemType": {
          "preset": "PHYSICAL"
        },
        "paymentOption": "FULL_PAYMENT_ONLINE"
      },
      {
        "id": "00000000-0000-0000-0000-000000000002",
        "quantity": 1,
        "catalogReference": {
          "catalogItemId": "c8539b66-7a44-fe18-affc-afec4be8562a",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
        },
        "productName": {
          "original": "Shirt",
          "translated": "Shirt"
        },
        "url": {
          "relativePath": "/product-page/shirt",
          "url": "https://example.wixsite.com"
        },
        "price": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "fullPrice": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "priceBeforeDiscounts": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "descriptionLines": [],
        "image": {
          "id": "3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "url": "https://static.wixstatic.com/media/3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "height": 1000,
          "width": 1000
        },
        "availability": {
          "status": "AVAILABLE"
        },
        "physicalProperties": {
          "sku": "364115376135191",
          "shippable": true
        },
        "couponScopes": [
          {
            "namespace": "stores",
            "group": {
              "name": "collection",
              "entityId": "00000000-000000-000000-000000000001"
            }
          },
          {
            "namespace": "stores",
            "group": {
              "name": "product",
              "entityId": "c8539b66-7a44-fe18-affc-afec4be8562a"
            }
          }
        ],
        "itemType": {
          "preset": "PHYSICAL"
        },
        "paymentOption": "FULL_PAYMENT_ONLINE"
      }
    ],
    "buyerInfo": {
      "userId": "c43190d2-eea3-493e-b6e8-f146850c6873"
    },
    "currency": "USD",
    "conversionCurrency": "USD",
    "buyerLanguage": "en",
    "siteLanguage": "en",
    "taxIncludedInPrices": false,
    "weightUnit": "KG",
    "subtotal": {
      "amount": "95",
      "convertedAmount": "95",
      "formattedAmount": "$95.00",
      "formattedConvertedAmount": "$95.00"
    },
    "checkoutId": "d0d530f0-45d9-4c2c-bd71-8ab07a058472",
    "appliedDiscounts": [
      {
        "coupon": {
          "id": "fbb94b06-7447-4161-9c48-59bfcdc39e77",
          "code": "SUMMERSALE10"
        }
      }
    ],
    "inSync": false,
    "createdDate": "2022-12-12T08:53:43.520Z",
    "updatedDate": "2022-12-12T10:46:41.959Z"
  }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Did this help?

DELETE

Delete Current Cart

Deletes the current site visitor's cart.

Note: This endpoint requires visitor or member authentication.

Permissions

Learn more about app permissions.

Endpoint

DELETE

https://www.wixapis.com/ecom/v1/carts/current

Request

This endpoint does not take any parameters.

Response Object

Returns an empty object.

Example shown:Deletes the current site visitor's cart

Request

cURL


curl -X DELETE \
  'https://www.wixapis.com/ecom/v1/carts/current' \
  -H 'Authorization: <AUTH>'

Response

JSON

{}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:

Cart Deleted

Did this help?

PATCH

Update Current Cart

Updates the current site visitor's cart.

Note: This endpoint requires visitor or member authentication.

Permissions

Learn more about app permissions.

Endpoint

PATCH

https://www.wixapis.com/ecom/v1/carts/current

Body Params

cartInfoCartInfo

Cart info.

couponCodestring

Coupon code. For more information, see Coupons API.

merchantDiscountsArray <MerchantDiscountInput>betamaxItems 100

Merchant discounts to apply to specific line items. If no lineItemIds are passed, the discount will be applied to the whole cart.

lineItemsArray <LineItem>maxItems 300

Catalog line items.

customLineItemsArray <CustomLineItem>betamaxItems 300

Custom line items. Custom line items don't trigger the Catalog service plugin.

To access and manage custom line items, your app must have the permission scope named "Manage eCommerce - Admin Permissions". Learn more about permission scopes.

Response Object

cartCart

Updated Cart.

Example shown:Update the current site visitor's cart

Apply a coupon to the current cart.

Request

cURL


curl -X PATCH \
  'https://www.wixapis.com/ecom/v1/carts/current' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "couponCode": "SUMMERSALE10"
  }'

Response

JSON


{
  "cart": {
    "id": "f97a2939-b1f3-41f2-9fc5-7ecea2060991",
    "lineItems": [
      {
        "id": "00000000-0000-0000-0000-000000000001",
        "quantity": 3,
        "catalogReference": {
          "catalogItemId": "c8539b66-7a44-fe18-affc-afec4be8562a",
          "appId": "215238eb-22a5-4c36-9e7b-e7c08025e04e"
        },
        "productName": {
          "original": "Shirt",
          "translated": "Shirt"
        },
        "url": {
          "relativePath": "/product-page/shirt",
          "url": "https://example.wixsite.com/my-site/product-page/shirt"
        },
        "price": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "fullPrice": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "priceBeforeDiscounts": {
          "amount": "10",
          "convertedAmount": "10",
          "formattedAmount": "$10.00",
          "formattedConvertedAmount": "$10.00"
        },
        "descriptionLines": [],
        "image": {
          "id": "3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "url": "https://static.wixstatic.com/media/3c76e2_c5331f937348492a97df87b0a3b34ea4~mv2.jpg",
          "height": 1000,
          "width": 1000
        },
        "availability": {
          "status": "AVAILABLE"
        },
        "physicalProperties": {
          "sku": "364115376135191",
          "shippable": true
        },
        "couponScopes": [
          {
            "namespace": "stores",
            "group": {
              "name": "collection",
              "entityId": "00000000-000000-000000-000000000001"
            }
          },
          {
            "namespace": "stores",
            "group": {
              "name": "product",
              "entityId": "c8539b66-7a44-fe18-affc-afec4be8562a"
            }
          }
        ],
        "itemType": {
          "preset": "PHYSICAL"
        },
        "paymentOption": "FULL_PAYMENT_ONLINE",
        "customLineItem": false
      }
    ],
    "buyerInfo": {
      "userId": "8b7eef41-7fbb-440b-928a-a442878112a3"
    },
    "currency": "USD",
    "conversionCurrency": "USD",
    "buyerLanguage": "en",
    "siteLanguage": "en",
    "taxIncludedInPrices": false,
    "weightUnit": "LB",
    "subtotal": {
      "amount": "30",
      "convertedAmount": "30",
      "formattedAmount": "$30.00",
      "formattedConvertedAmount": "$30.00"
    },
    "appliedDiscounts": [
      {
        "coupon": {
          "id": "e463550b-220a-428f-82d9-8d11c3c1acd7",
          "code": "SUMMERSALE10"
        }
      }
    ],
    "inSync": false,
    "createdDate": "2023-02-13T10:34:55.727Z",
    "updatedDate": "2023-02-13T13:37:21.586Z",
    "contactInfo": {
      "address": {
        "country": "US",
        "subdivision": "US-NY",
        "city": "New York",
        "postalCode": "10011",
        "addressLine": "235 West 23rd Street",
        "addressLine2": "3rd floor",
        "countryFullname": "United States",
        "subdivisionFullname": "New York"
      },
      "contactDetails": {
        "firstName": "Jane",
        "lastName": "Doe",
        "phone": "+1234567890"
      }
    }
  }
}

Errors

This method doesn’t return any custom errors, but may return standard errors. Learn more about standard Wix errors.

Event TriggersThis method triggers the following events:

Cart Updated

Did this help?