Process shipping request

Ecwid checkout offers customers a selection between Shipping and Pickup delivery options:

If a customer selects the Ship to address option, Ecwid asks for the delivery address: country, state, city, etc. All of the address details will be sent to the shippingURL of the application.
If a customer selects the I'll pick it up myself option, Ecwid only asks for the name and phone number, both of which are not sent to the shippingURL of the application.

Therefore, upon receiving a new shipping request, check if it has the shippingAddress object with address details. If there is no such object, it means that the customer chose the Pickup option. Adjust your shipping rate calculation logic accordingly.

Request details

Ecwid will send order information in the body of a POST HTTP request.

📘
Ecwid can cache the requests to your endpoint. How shipping method works

POST https://mycoolapp.com/integration HTTP/1.1

{
  "storeId": 1003,
  "merchantAppSettings": {},
  "cart": {
    "id": "IVSZF",
    "orderNumber": 288476065,
    "vendorOrderNumber": "IVSZF",
    "subtotal": 0,
    "ipAddress": "79.142.91.78",
    "couponDiscount": 0,
    "paymentStatus": "INCOMPLETE",
    "fulfillmentStatus": "NEW",
    "refererUrl": "https://store.ecwid.com/",
    "orderComments": "test",
    "volumeDiscount": 0,
    "membershipBasedDiscount": 0,
    "totalAndMembershipBasedDiscount": 0,
    "discount": 0,
    "customerGroupId": null,
    "customerGroup": null,
    "customerId": null,
    "customerEmail": "[email protected]",
    "discountCoupon": {
      "id": 135823561,
      "ownerId": 1003,
      "name": "Coupon",
      "code": "YOURCODE",
      "discountType": "PERCENT",
      "status": "ACTIVE",
      "discount": 10,
      "launchDate": "2019-09-30 23:00:00 +0000",
      "expirationDate": null,
      "totalLimit": null,
      "usesLimit": "UNLIMITED",
      "applicationLimit": "UNLIMITED",
      "creationDate": "2021-09-21 13:40:21 +0000",
      "orderCount": 0,
      "legacyCatalogLimit": null,
      "catalogLimit": null,
      "repeatCustomerOnly": false,
      "newCustomerOnly": false,
      "parentId": 41576009,
      "customerId": 0,
      "cartId": 1950723716,
      "updateDate": "2021-02-23 02:01:30 +0000"
    },
    "discountInfo": null,
    "handlingFee": null,
    "hidden": false,
    "items": [
      {
        "weight": 120,
        "price": 2130,
        "amount": 1,
        "productId": 352841275,
        "name": "Test Product",
        "categoryId": -1,
        "sku": "00002312",
        "selectedOptions": [
          {
            "name": "Size",
            "nameTranslated": {
              "en": "Size"
            },
            "type": "CHOICE",
            "value": "S",
            "valueTranslated": {
              "en": "S"
            },
            "valuesArray": [
              "S"
            ],
            "valuesArrayTranslated": null,
            "files": null,
            "selections": [
              {
                "selectionTitle": "S",
                "selectionModifier": 0,
                "selectionModifierType": "ABSOLUTE"
              }
            ]
          }
        ],
        "dimensions": {
          "length": 10,
          "width": 20,
          "height": 30
        },
        "productPrice": 2130,
        "categoryIds": [],
        "categories": [],
        "quantity": null,
        "unlimited": true,
        "inStock": true,
        "priceInProductList": 2130,
        "isShippingRequired": true,
        "productClassId": 0,
        "enabled": true,
        "warningLimit": 0,
        "fixedShippingRateOnly": false,
        "fixedShippingRate": 0,
        "options": [
          {
            "type": "SELECT",
            "name": "Size",
            "defaultChoice": 0,
            "required": false,
            "choices": [
              {
                "text": "S",
                "priceModifier": 0,
                "priceModifierType": "ABSOLUTE"
              },
              {
                "text": "M",
                "priceModifier": 0,
                "priceModifierType": "ABSOLUTE"
              }
            ]
          }
        ],
        "wholesalePrices": [],
        "compareToPrice": null,
        "url": "https://store.ecwid.com/#!/Test-Product/p/352841275",
        "created": "2021-05-03 18:23:13 +0000",
        "updated": "2021-09-21 13:42:21 +0000",
        "createTimestamp": 1620066193,
        "updateTimestamp": 1632231741,
        "defaultCombinationId": 222806564,
        "imageUrl": null,
        "thumbnailUrl": null,
        "smallThumbnailUrl": null,
        "hdThumbnailUrl": null,
        "originalImageUrl": null,
        "originalImage": null,
        "borderInfo": null,
        "galleryImages": [],
        "defaultCategoryId": 0,
        "seoTitle": "",
        "seoDescription": "",
        "favorites": {
          "count": 0,
          "displayedCount": "0"
        },
        "attributes": [
          {
            "id": 27942320,
            "name": "UPC",
            "type": "UPC",
            "value": "TEST",
            "show": "DESCR"
          },
          {
            "id": 27942321,
            "name": "Brand",
            "type": "BRAND",
            "value": "GENERIC",
            "show": "DESCR"
          }
        ],
        "relatedProducts": {
          "productIds": [],
          "relatedCategory": {
            "enabled": false,
            "categoryId": 0,
            "productCount": 5
          }
        },
        "combinations": [
          {
            "id": 222806563,
            "sku": "00002444",
            "combinationNumber": 2,
            "options": [
              {
                "name": "Size",
                "nameTranslated": {
                  "en": "Size"
                },
                "value": "M",
                "valueTranslated": {
                  "en": "M"
                }
              }
            ],
            "smallThumbnailUrl": null,
            "hdThumbnailUrl": null,
            "thumbnailUrl": null,
            "imageUrl": null,
            "originalImageUrl": null,
            "price": null,
            "defaultDisplayedPrice": 2130,
            "defaultDisplayedPriceFormatted": "$2 130.00",
            "compareToPrice": null,
            "wholesalePrices": null,
            "quantity": null,
            "unlimited": true,
            "inStock": true,
            "warningLimit": 0,
            "weight": 190,
            "borderInfo": null,
            "attributes": [],
            "isShippingRequired": null
          },
          {
            "id": 222806564,
            "sku": "00002312",
            "combinationNumber": 1,
            "options": [
              {
                "name": "Size",
                "nameTranslated": {
                  "en": "Size"
                },
                "value": "S",
                "valueTranslated": {
                  "en": "S"
                }
              }
            ],
            "smallThumbnailUrl": null,
            "hdThumbnailUrl": null,
            "thumbnailUrl": null,
            "imageUrl": null,
            "originalImageUrl": null,
            "price": null,
            "defaultDisplayedPrice": 2130,
            "defaultDisplayedPriceFormatted": "$2 130.00",
            "compareToPrice": null,
            "wholesalePrices": null,
            "quantity": null,
            "unlimited": true,
            "inStock": true,
            "warningLimit": 0,
            "weight": 120,
            "borderInfo": null,
            "attributes": [],
            "isShippingRequired": null
          }
        ],
        "showOnFrontpage": 2
      }
    ],
    "shippingAddress": {
      "street": "test",
      "city": "test",
      "countryCode": "US",
      "postalCode": "10001",
      "stateOrProvinceCode": "NY",
      "stateOrProvinceName": "New York"
    },
    "originAddress": {
      "street": "1 Teema, Harris Road, South End\n",
      "city": "Port Elizabeth",
      "countryCode": "DE",
      "postalCode": "54570",
      "stateOrProvinceCode": ""
    },
    "weight": 120,
    "weightUnit": "kg",
    "dimensionUnit": "CM",
    "currency": "USD",
    "predictedPackages": [
      {
        "length": 10,
        "width": 20,
        "height": 30,
        "weight": 120,
        "declaredValue": 2130
      }
    ],
    "paymentMethod": null,
    "extraFields": null
  },
  "lang": "en"  
}

Name	Type	Description
storeId	number	Ecwid store ID
merchantAppSettings	json	Merchant settings for your integration set up by your code. More details
cart	<CartDetails>	All available cart information when customer's cart is updated at checkout
lang	string	Customer's storefront language (e.g. `en`)

CartDetails

Name	Type	Description
subtotal	number	Order subtotal. Includes the sum of all products' cost in the order
ipAddress	string	Customer IP
paymentStatus	string	Payment status. Supported values: `AWAITING_PAYMENT` `PAID` `CANCELLED` `REFUNDED` `INCOMPLETE`
fulfillmentStatus	string	Fulfilment status. Supported values: `AWAITING_PROCESSING` `PROCESSING` `SHIPPED` `DELIVERED` `WILL_NOT_DELIVER` `RETURNED`
refererUrl	string	URL of the page when order was placed (without hash (#) part)
orderComments	string	Order comments
couponDiscount	number	Discount applied to order using a coupon
volumeDiscount	number	Sum of discounts based on subtotal. Is included into the `discount` field
discount	number	The sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of `couponDiscount` and `discount` field values
membershipBasedDiscount	number	Sum of discounts based on customer group. Is included into the `discount` field
totalAndMembershipBasedDiscount	number	The sum of discount based on subtotal AND customer group. Is included into the `discount` field
discountCoupon	<DiscountCouponInfo>	Information about applied coupon
discountInfo	Array<DiscountInfo>	Information about applied discounts (coupons are not included)
customerGroupId	number	Customer group ID
customerGroup	string	The name of group (membership) the customer belongs to
customerId	number	Unique customer internal ID (if the order is placed by a registered user)
items	Array<OrderItems>	Array of customer's order items with basic details. Only includes items that that require shipping and have shipping set as global or global + fixed rate per item
weight	number	Total weight of the order
weightUnit	string	Active weight units in the store at the moment of the request. Formats and units
currency	string	Active currency in the store at the moment of the request
predictedPackages	Array<PredictedPackage>	Predicted information about the packages to ship items in to customer
shippingAddress	<ShippingAddressInfo>	Shipping address details (destination)
originAddress	<OriginAddressInfo>	Origin address details (departure)
dimensionUnit	string	Active dimension units of a store at the moment of the request. Possible values: `IN`,`YD`,`CM`,`MM`
paymentMethod	string	Payment method used by customer
handlingFee	<HandlingFeeInfo>	Handling fee details
email	string	Customer email address
extraFields	<ExtraFieldsInfo>	Additional optional information about order. Total storage of extra fields cannot exceed 8Kb. See Order extra fields

OrderItems

Field	Type	Description
productId	number	Store product ID
categoryId	number	ID of category this product was added to cart from. If the product was added to cart from API or Search page, `categoryID` will return `-1`
price	number	Price of ordered item in the cart
weight	number	Product weight
sku	string	Product SKU. If the chosen options match a variation, this will be a variation SKU.
amount	number	Amount purchased
name	string	Product name
selectedOptions	Array<OrderItemOption>	Product options values selected by the customer
dimensions	<OrderItemDimensions>	Product dimensions info
quantity	number	Amount of product items in stock. This field is omitted for the products with unlimited stock
unlimited	boolean	`true` if the product has unlimited stock
inStock	boolean	`true` if the product or any of its variations is in stock (quantity is more than zero) or has unlimited quantity. `false` otherwise.
name	string	Product title
productPrice	number	Product price set by store owner
priceInProductList	number	Product price displayed in a storefront. May differ from the price value when the product has options and variations and the default variation's price is different from the base product price. Does not include taxes
wholesalePrices	Array<WholesalePrice>	Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPrice	number	Product's sale price displayed strike-out in the customer frontend Omitted if empty
isShippingRequired	boolean	`true` if product requires shipping, `false` otherwise
url	string	URL of the product's details page in the store. Learn more
created	string	Date and time of the product creation. Example: `2014-07-30 10:32:37 +0000`
updated	string	Product last update date/time
createTimestamp	number	The date of product creation in UNIX Timestamp format, e.g `1427268654`
updateTimestamp	number	Product last update date in UNIX Timestamp format, e.g `1427268654`
productClassId	number	Id of the class (type) that this product belongs to. `0` value means the product is of the default 'General' class. See also: Product types and attributes in Ecwid
enabled	boolean	`true` if product is enabled, `false` otherwise. Disabled products are not displayed in the store front.
options	Array<ProductOption>	A list of the product options. Empty (`[]`) if no options are specified for the product.
warningLimit	number	The minimum 'warning' amount of the product items in stock, if set. When the product quantity reaches this level, the store administrator gets an email notification.
fixedShippingRateOnly	boolean	`true` if shipping cost for this product is calculated as 'Fixed rate per item' (managed under the "Tax and Shipping" section of the product management page in Ecwid Control panel). `false` otherwise. With this option on, the `fixedShippingRate` field specifies the shipping cost of the product
fixedShippingRate	number	When `fixedShippingRateOnly` is `true`, this field sets the product fixed shipping cost per item. When `fixedShippingRateOnly` is `false`, the value in this field is treated as an extra shipping cost the product adds to the global calculated shipping
defaultCombinationId	number	Identifier of the default product variation, which is defined by the default values of product options.
thumbnailUrl	string	URL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of the biggest dimension is 400px. The original uploaded product image is available in the `originalImageUrl` field.
imageUrl	string	URL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the `originalImageUrl` field.
smallThumbnailUrl	string	URL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the `originalImageUrl` field.
hdThumbnailUrl	string	Product HD thumbnail URL resized to fit 800x800px
originalImageUrl	string	URL of the original not resized product image
originalImage	<ImageDetails>	Details of the product image
galleryImages	Array<GalleryImage>	List of the product gallery images
categoryIds	Array<number>	List of the categories, which the product belongs to. If no categories provided, product will be displayed on the store front page, see `showOnFrontpage` field
categories	Array<CategoriesInfo>	List of the categories, which the product belongs to, with brief details. If no categories provided, product belogs to store front page, see `showOnFrontpage` field
seoTitle	string	Page title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescription	string	Page description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryId	number	Identifier of the default category of the product
favorites	<FavoritesStats>	Product favorites stats
attributes	Array<AttributeValue>	Product attributes and their values
relatedProducts	<RelatedProducts>	Related or "You may also like" products of the product
combinations	Array<Variation>	List of the product variations
showOnFrontpage	number	A positive number indicates the position (index) of a product in the store front page – the smaller the number, the higher the product is displayed on a page. A negative value means the product is not shown in the store front page

OrderItemOption

Field	Type	Description
name	string	Option name
type	string	Option type. One of: `CHOICE` (dropdown or radio button) `CHOICES` (checkboxes) `TEXT` (text input and text area) `DATE` (date/time) `FILES` (upload file option)
value	string	Selected/entered option value(s) as a string. For the `CHOICES` type, provides a string with all chosen values (comma-separated). You can use this to simply print out all selected values.
valuesArray	Array	Selected option values as an array. For the `CHOICES` type, provides an array with the chosen values so you can iterate through them in your app.
files	Array<OrderItemOptionFile>	Attached files (if the option type is `FILES`)

OrderItemOptionFile

Field	Type	Description
id	number	File ID
name	string	File name
size	number	File size in bytes
url	string	File URL

OrderItemDimensions

Field	Type	Description
length	number	Length of a product
width	number	Width of a product
height	number	Height of a product

FavoritesStats

Field	Type	Description
count	number	The actual number of 'likes' of this product
displayedCount	string	The displayed number of likes. May differ from the `count` if, for example, the value is more than 1000, than it will show 1K instead of the precise number

WholesalePrice

Field	Type	Description
quantity	number	Number of product items on this wholesale tier
price	number	Product price on the tier

ProductOption

Field	Type	Description
type	string	One of `SELECT`, `RADIO`, `CHECKBOX`, `TEXTFIELD`, `TEXTAREA`, `DATE`, `FILES`
name	string	Product option name, e.g. `Color`
choices	Array<ProductOptionChoice>	All possible option selections for the types `SELECT`, `CHECKBOX` or `RADIO`. This field is omitted for the product option with no selection (e.g. text, datepicker or upload file options)
defaultChoice	number	The number, starting from `0`, of the option's default selection. Only presents if the type is `SELECT`, `CHECKBOX` or `RADIO`.
required	boolean	`true` if this option is required, `false` otherwise. Default is `false`

ImageDetails

Field	Type	Description
url	string	Image URL
width	integer	Image width
height	integer	Image height

GalleryImage

Field	Type	Description
id	number	Internal gallery image ID
alt	string	Image description, displayed in the image tag's alt attribute
url	string	Deprecated. Original image URL. Equals `originalImageUrl`
thumbnail	string	Deprecated. Image thumbnail URL resized to fit 160x160px. Equals `smallThumbnailUrl`
thumbnailUrl	string	URL of the product thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of the biggest dimension is 400px. The original uploaded product image is available in the `originalImageUrl` field.
imageUrl	string	URL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the `originalImageUrl` field.
smallThumbnailUrl	string	URL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the `originalImageUrl` field.
hdThumbnailUrl	string	Product HD thumbnail URL resized to fit 800x800px
originalImageUrl	string	URL of the original not resized product image
width	number	Image width
height	number	Image height
orderby	number	The sort weight of the image in the gallery images list. The less the number, the closer the image to the beginning of the gallery

CategoriesInfo

Field	Type	Description
id	number	Category ID
enabled	boolean	`true` if category is enabled, `false` otherwise

AttributeValue

Field	Type	Description
id	number	Unique attribute ID. See Product Classes for the information on attribute IDs
name	string	Attribute displayed name
value	string	Attribute value
type	string	Attribute type. There are user-defined attributes, general attributes and special 'price per unit’ attributes. The 'type’ field contains one of the following: `CUSTOM`, `UPC`, `BRAND`, `GENDER`, `AGE_GROUP`, `COLOR`, `SIZE`, `PRICE_PER_UNIT`, `UNITS_IN_PRODUCT`
show	string	Defines where to display the product attribute value:. Supported values: `NOTSHOW`, `DESCR`, `PRICE`

RelatedProducts

Field	Type	Description
productIds	Array<number>	IDs of the related products
relatedCategory	RelatedCategory	Describes the "N random related products from a category" option

RelatedCategory

Field	Type	Description
enabled	boolean	`true` if the "N random related products from a category" option is enabled. `false` otherwise
categoryId	number	Id of the related category. Zero value means "any category", that is, random products from the whole store.
productCount	number	Number of random products from the given category to be shown as related

Variation

Field	Type	Description
id	number	Variation ID
combinationNumber	number	Variation # number, which is displayed in the variations table in Control panel
options	Array<OptionValue>	Set of options that identifies this variation. An array of name-value pairs
sku	string	Variation SKU. Omitted if the variation inherits the base product's SKU
thumbnailUrl	string	URL of the product variation thumbnail displayed on the product list pages. Thumbnails size is defined in the store settings. Default size of biggest dimension is 400px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the `originalImageUrl` field.
imageUrl	string	URL of the product variation image resized to fit 1500x1500px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the `originalImageUrl` field.
smallThumbnailUrl	string	URL of the product variation thumbnail resized to fit 160x160px. Omitted if the variation inherits the base product's image. The original uploaded product image is available in the `originalImageUrl` field.
hdThumbnailUrl	string	Product variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product's image.
originalImageUrl	string	URL of the original not resized product variation image. Omitted if the variation inherits the base product's image.
quantity	number	Amount of the variation items in stock. Omitted if the variation inherits the base product's quantity.
unlimited	boolean	`true` if the variation has unlimited stock (that is, never runs out)
price	number	Variation price. Omitted if the variation inherits the base product's price.
wholesalePrices	Array<WholesalePrice>	Sorted array of the variation's wholesale price tiers (quantity limit and price). Omitted if the variation inherits the base product's tiered price settings.
weight	number	Variation weight in the units defined in store settings. Omitted if the variation inherits the base product's weight.
warningLimit	number	The minimum 'warning' amount of the product items in stock for this variation, if set. When the variation in stock amount reaches this level, the store administrator gets an email notification. Omitted if the variation inherits the base product's settings.
attributes	Array<AttributeValue>	Variation's UPC attribute and its value
compareToPrice	number	Variation's sale price displayed strike-out in the customer frontend Omitted if empty

OptionValue

Field	Type	Description
name	string	Option name
value	string	Option value

ProductOptionChoice

Field	Type	Description
text	string	Option selection text, e.g. 'Green'.
priceModifier	number	Percent or absolute value of the option's price markup. Positive, negative and zero values are allowed. Default is `0`
priceModifierType	string	Option markup calculation type. `PERCENT` or `ABSOLUTE`. Default is `ABSOLUTE`.

DiscountCouponInfo

Field	Type	Description
name	string	Coupon title in store control panel
code	string	Coupon code
discountType	string	Discount type: `ABS`, `PERCENT`, `SHIPPING`, `ABS_AND_SHIPPING`, `PERCENT_AND_SHIPPING`
status	string	Discount coupon state: `ACTIVE`, `PAUSED`, `EXPIRED` or `USEDUP`
discount	number	Discount amount
launchDate	string	The date of coupon launch, e.g. `2014-06-06 08:00:00 +0000`
expirationDate	string	Coupon expiration date, e.g. `2014-06-06 08:00:00 +0000`
totalLimit	number	The minimum order subtotal the coupon applies to
usesLimit	string	Number of uses limitation: `UNLIMITED`, `ONCEPERCUSTOMER`, `SINGLE`
repeatCustomerOnly	boolean	Coupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDate	string	Coupon creation date
orderCount	number	Number of uses
catalogLimit	<DiscountCouponCatalogLimit>	Products and categories the coupon can be applied to

DiscountInfo

Field	Type	Description
value	number	Discount value
type	string	Discount type: `ABS` or `PERCENT`
base	string	Discount base, one of `ON_TOTAL`, `ON_MEMBERSHIP`, `ON_TOTAL_AND_MEMBERSHIP`
order_total	number	Minimum order subtotal the discount applies to

ExtraFieldsInfo

Field	Type	Description
YOUR_FIELD_NAME	string	Your custom name saved for the order extra field. The value length cannot exceed 255 characters

PredictedPackage

Name	Type	Description
height	number	Height of a predicted package
width	number	Width of a predicted package
length	number	Length of a predicted package
weight	number	Total weight of a predicted package
declaredValue	number	Declared value of a predicted package (subtotal of items in package)

ShippingAddressInfo

Name	Type	Description
street	string	Customer's street
city	string	Customer's city
countryCode	string	Customer's country code in Ecwid
countryName	string	Customer's country name in Ecwid
postalCode	string	Customer's postal code
stateOrProvinceCode	string	Customer's state or province code in Ecwid
stateOrProvinceName	string	Customer's state or province name in Ecwid

OriginAddressInfo

Name	Type	Description
street	string	Merchant's street
city	string	Merchant's city
countryCode	string	Merchant's country code in Ecwid
postalCode	string	Merchant's postal code
stateOrProvinceCode	string	Merchant's state or province code in Ecwid

HandlingFeeInfo

Field	Type	Description
name	string	Handling fee name set by store admin. E.g. `Wrapping`
value	number	Handling fee value
description	string	Handling fee description for customer