NAV

Shipping request and response

Request

Ecwid will send order information in the body of a POST HTTP request in the following format:

Request from Ecwid example

POST https://mycoolapp.com/integration HTTP/1.1
{
    "storeId": 35002,
    "merchantAppSettings": {
        "public":"{color : \"red\", storeName : \"Cool Socks Ltd.\"}",
        "dimensions": "5x10x7",
        "userId": "12345"
    },
    "cart": {
        "subtotal": 7.08,
        "ipAddress": "127.0.0.1",
        "couponDiscount": 0,
        "paymentStatus": "INCOMPLETE",
        "fulfillmentStatus": "NEW",
        "refererUrl": "https://mdemo.ecwid.com/",
        "orderComments": "Leave at the front porch.",
        "volumeDiscount": 5,
        "membershipBasedDiscount": 0.14,
        "totalAndMembershipBasedDiscount": 1,
        "discount": 6.14,
        "customerGroupId": 123456,
        "customerGroup": "Gold members",
        "customerId": 23649002,
        "paymentMethod": "Purchase order",
        "email": "johnsmith@example.com",

        "discountCoupon": {
                "name": "Coupon # 3",
                "code": "5PERCENTOFF",
                "discountType": "PERCENT",
                "status": "ACTIVE",
                "discount": 5,
                "launchDate": "2014-06-06 00:00:00 +0000",
                "usesLimit": "UNLIMITED",
                "repeatCustomerOnly": false,
                "creationDate": "2014-09-20 19:58:49 +0000",
                "orderCount": 0
        },
        "discountInfo": [
            {
                "orderTotal": 1,
                "value": 5,
                "type": "ABS",
                "base": "ON_TOTAL",
                "membershipId": 0
            },
            {
                "orderTotal": 1,
                "value": 2,
                "type": "PERCENT",
                "base": "ON_MEMBERSHIP",
                "membershipId": 0
            },
            {
                "orderTotal": 1,
                "value": 1,
                "type": "ABS",
                "base": "ON_TOTAL_AND_MEMBERSHIP",
                "membershipId": 0
            }
        ],
        "handlingFee": {
            "name": "Handling Fee",
            "value": 0,
            "description": ""
        },
        "items": [
            {  
                "weight":0.25,
                "price":18.95,
                "amount":1,
                "productId":85607123,
                "name":"All-Weather\u0026trade; Solid Black Mini Umbrella",
                "categoryId":-1,
                "sku":"GFUMLT",
                "selectedOptions":null,
                "dimensions":{  
                   "length":9.0,
                   "width":1.0,
                   "height":7.0
                },
                "productPrice":18.95,
                "categoryIds":[],
                "categories":[],
                "quantity":16658,
                "unlimited":false,
                "inStock":true,
                "priceInProductList":18.95,
                "isShippingRequired":true,
                "productClassId":0,
                "enabled":true,
                "warningLimit":0,
                "fixedShippingRateOnly":false,
                "fixedShippingRate":0.0,
                "options":null,
                "wholesalePrices":null,
                "compareToPrice":null,
                "url":"https://mdemo.ecwid.com/#!/All-Weather\u0026trade-Solid-Black-Mini-Umbrella/p/85607123",
                "created":"2017-06-06 11:47:18 +0000",
                "updated":"2017-09-18 08:22:29 +0000",
                "createTimestamp":1496749638,
                "updateTimestamp":1505722949,
                "defaultCombinationId":0,
                "imageUrl":null,
                "thumbnailUrl":null,
                "smallThumbnailUrl":null,
                "hdThumbnailUrl":null,
                "originalImageUrl":null,
                "originalImage":null,
                "borderInfo":null,
                "galleryImages":[],
                "defaultCategoryId":0,
                "seoTitle":"All-Weather\u0026trade; Solid Black Mini Umbrella",
                "seoDescription":"This 40\u0026quot; super mini umbrella folds up to a compact 9\u0026quot; x 1-3/4\u0026quot; x 1-1/4\u0026quot; to carry in your purse or briefcase. The uni-chrome ribs, plastic handle and self tips combine to make this a sturdy and functional accessory. Comes in a clear, plastic polypropylene case.",
                "favorites":{  
                   "count":0,
                   "displayedCount":"0"
                },
                "attributes":[],
                "relatedProducts":{  
                   "productIds":[],
                   "relatedCategory":{  
                      "enabled":false,
                      "categoryId":0,
                      "productCount":1
                   }
                },
                "combinations":[],
                "showOnFrontpage":1
             }
        ],
        "predictedPackages":[  
            {  
                "length":12.5,
                "width":6,
                "height":3.5,
                "weight":1.5,
                "declaredValue":7.08
            }
        ],
        "shippingAddress": {
            "street": "5th Avenue",
            "city": "New York",
            "countryCode": "US",
            "postalCode": "10002",
            "stateOrProvinceCode": "NY",
            "stateOrProvinceName": "New York"
        },
        "originAddress": {
            "street": "Columbus Street, 5",
            "city": "Idaho Falls",
            "countryCode": "US",
            "postalCode": "30135",
            "stateOrProvinceCode": "GA"
        },
        "weight": 1.5,
        "weightUnit": "lbs",
        "currency": "USD",
        "dimensionUnit" : "MM",
        "handlingFee": {
            "name": "Wrapping",
            "value": 2,
            "description": "Silk paper wrapping"
        },
        "extraFields": {
            "platform": {
                "value": "adobe_muse"
            },
            "AFF_ID": {
                "value": "fb-123"
            },
            "how_did_you_find_us": {
                "title": "How you found us?",
                "value": "TV show",
                "order_details_display_section": "order_comments"
            }
        }
    }
}
NameTypeDescription
storeIdnumberEcwid store ID
merchantAppSettingsjsonMerchant settings for your integration set up by your code. More details
cart<CartDetails>Offset from the beginning of the returned items list (for paging)

CartDetails

NameTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
ipAddressstringCustomer IP
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
couponDiscountnumberDiscount applied to order using a coupon
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
discountnumberThe 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
membershipBasedDiscountnumberSum of discounts based on customer group. Is included into the discount field
totalAndMembershipBasedDiscountnumberThe sum of discount based on subtotal AND customer group. Is included into the discount field
discountCoupon<DiscountCouponInfo>Information about applied coupon
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
handlingFee<HandlingFeeInfo>Handling fee details
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
itemsArray<OrderItems>Array of customer’s order items with basic details
weightnumberTotal weight of the order
weightUnitstringActive weight units in the store at the moment of the request. Formats and units
currencystringActive currency in the store at the moment of the request
predictedPackagesArray<PredictedPackage>Predicted information about the packages to ship items in to customer
shippingAddress<ShippingAddressInfo>Shipping address details (destination)
originAddress<OriginAdressInfo>Origin address details (departure)
dimensionUnitstringActive dimension units of a store at the moment of the request. Possible values: IN,YD,CM,MM
paymentMethodstringPayment method used by customer
handlingFee<HandlingFeeInfo>Handling fee details
emailstringCustomer email address
extraFields<ExtraFieldsInfo>Additional optional information about order. Total storage of extra fields cannot exceed 8Kb. See Order extra fields

OrderItems

FieldTypeDescription
productIdnumberStore product ID
categoryIdnumberID of the category this product belongs to. If the product belongs to many categories, categoryID will return the ID of the default product category. If the product doesn’t belong to any category, 0 is returned
pricenumberPrice of ordered item in the cart
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a variation, this will be a variation SKU.
amountnumberAmount purchased
namestringProduct name
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
dimensions<OrderItemDimensions>Product dimensions info
quantitynumberAmount of product items in stock. This field is omitted for the products with unlimited stock
unlimitedbooleantrue if the product has unlimited stock
inStockbooleantrue if the product or any of its variations is in stock (quantity is more than zero) or has unlimited quantity. false otherwise.
namestringProduct title
productPricenumberProduct price set by store owner
priceInProductListnumberProduct 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
wholesalePricesArray<WholesalePrice>Sorted array of wholesale price tiers (quantity limit and price pairs)
compareToPricenumberProduct’s sale price displayed strike-out in the customer frontend Omitted if empty
isShippingRequiredbooleantrue if product requires shipping, false otherwise
urlstringURL of the product’s details page in the store. Learn more
createdstringDate and time of the product creation. Example: 2014-07-30 10:32:37 +0000
updatedstringProduct last update date/time
createTimestampnumberThe date of product creation in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberProduct last update date in UNIX Timestamp format, e.g 1427268654
productClassIdnumberId 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
enabledbooleantrue if product is enabled, false otherwise. Disabled products are not displayed in the store front.
optionsArray<ProductOption>A list of the product options. Empty ([]) if no options are specified for the product.
warningLimitnumberThe 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.
fixedShippingRateOnlybooleantrue 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
fixedShippingRatenumberWhen 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
defaultCombinationIdnumberIdentifier of the default product variation, which is defined by the default values of product options.
thumbnailUrlstringURL 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.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
originalImage<ImageDetails>Details of the product image
galleryImagesArray<GalleryImage>List of the product gallery images
categoryIdsArray<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
categoriesArray<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
seoTitlestringPage title to be displayed in search results on the web. Recommended length is under 55 characters
seoDescriptionstringPage description to be displayed in search results on the web. Recommended length is under 160 characters
defaultCategoryIdnumberIdentifier of the default category of the product
favorites<FavoritesStats>Product favorites stats
attributesArray<AttributeValue>Product attributes and their values
relatedProducts<RelatedProducts>Related or “You may also like” products of the product
combinationsArray<Variation>List of the product variations
showOnFrontpagenumberA 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

FieldTypeDescription
namestringOption name
typestringOption type. One of:
  • CHOICE (dropdown or radio button)
  • CHOICES (checkboxes)
  • TEXT (text input and text area)
  • DATE (date/time)
  • FILES (upload file option)
valuestringSelected/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.
valuesArrayArraySelected 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.
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

OrderItemOptionFile

FieldTypeDescription
idnumberFile ID
namestringFile name
sizenumberFile size in bytes
urlstringFile URL

OrderItemDimensions

FieldTypeDescription
lengthnumberLength of a product
widthnumberWidth of a product
heightnumberHeight of a product

FavoritesStats

FieldTypeDescription
countnumberThe actual number of 'likes’ of this product
displayedCountstringThe 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

FieldTypeDescription
quantitynumberNumber of product items on this wholesale tier
pricenumberProduct price on the tier

ProductOption

FieldTypeDescription
typestringOne of SELECT, RADIO, CHECKBOX, TEXTFIELD, TEXTAREA, DATE, FILES
namestringProduct option name, e.g. Color
choicesArray<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)
defaultChoicenumberThe number, starting from 0, of the option’s default selection. Only presents if the type is SELECT, CHECKBOX or RADIO.
requiredbooleantrue if this option is required, false otherwise. Default is false

ImageDetails

FieldTypeDescription
urlstringImage URL
widthintegerImage width
heightintegerImage height

GalleryImage

FieldTypeDescription
idnumberInternal gallery image ID
altstringImage description, displayed in the image tag’s alt attribute
urlstringDeprecated. Original image URL. Equals originalImageUrl
thumbnailstringDeprecated. Image thumbnail URL resized to fit 160x160px. Equals smallThumbnailUrl
thumbnailUrlstringURL 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.
imageUrlstringURL of the product image resized to fit 1500x1500px. The original uploaded product image is available in the originalImageUrl field.
smallThumbnailUrlstringURL of the product thumbnail resized to fit 160x160px. The original uploaded product image is available in the originalImageUrl field.
hdThumbnailUrlstringProduct HD thumbnail URL resized to fit 800x800px
originalImageUrlstringURL of the original not resized product image
widthnumberImage width
heightnumberImage height
orderbynumberThe 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

FieldTypeDescription
idnumberCategory ID
enabledbooleantrue if category is enabled, false otherwise

AttributeValue

FieldTypeDescription
idnumberUnique attribute ID. See Product Classes for the information on attribute IDs
namestringAttribute displayed name
valuestringAttribute value
typestringAttribute 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
showstringDefines where to display the product attribute value:. Supported values: NOTSHOW, DESCR, PRICE

RelatedProducts

FieldTypeDescription
productIdsArray<number>IDs of the related products
relatedCategoryRelatedCategoryDescribes the “N random related products from a category” option

RelatedCategory

FieldTypeDescription
enabledbooleantrue if the “N random related products from a category” option is enabled. false otherwise
categoryIdnumberId of the related category. Zero value means “any category”, that is, random products from the whole store.
productCountnumberNumber of random products from the given category to be shown as related

Variation

FieldTypeDescription
idnumberVariation ID
combinationNumbernumberVariation # number, which is displayed in the variations table in Control panel
optionsArray<OptionValue>Set of options that identifies this variation. An array of name-value pairs
skustringVariation SKU. Omitted if the variation inherits the base product’s SKU
thumbnailUrlstringURL 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.
imageUrlstringURL 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.
smallThumbnailUrlstringURL 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.
hdThumbnailUrlstringProduct variation HD thumbnail URL resized to fit 800x800px. Omitted if the variation inherits the base product’s image.
originalImageUrlstringURL of the original not resized product variation image. Omitted if the variation inherits the base product’s image.
quantitynumberAmount of the variation items in stock. Omitted if the variation inherits the base product’s quantity.
unlimitedbooleantrue if the variation has unlimited stock (that is, never runs out)
pricenumberVariation price. Omitted if the variation inherits the base product’s price.
wholesalePricesArray<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.
weightnumberVariation weight in the units defined in store settings. Omitted if the variation inherits the base product’s weight.
warningLimitnumberThe 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.

OptionValue

FieldTypeDescription
namestringOption name
valuestringOption value

ProductOptionChoice

FieldTypeDescription
textstringOption selection text, e.g. 'Green’.
priceModifiernumberPercent or absolute value of the option’s price markup. Positive, negative and zero values are allowed. Default is 0
priceModifierTypestringOption markup calculation type. PERCENT or ABSOLUTE. Default is ABSOLUTE.

DiscountCouponInfo

FieldTypeDescription
namestringCoupon title in store control panel
codestringCoupon code
discountTypestringDiscount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING
statusstringDiscount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP
discountnumberDiscount amount
launchDatestringThe date of coupon launch, e.g. 2014-06-06 08:00:00 +0000
expirationDatestringCoupon expiration date, e.g. 2014-06-06 08:00:00 +0000
totalLimitnumberThe minimum order subtotal the coupon applies to
usesLimitstringNumber of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE
repeatCustomerOnlybooleanCoupon usage limitation flag identifying whether the coupon works for all customers or only repeat customers
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP
order_totalnumberMinimum order subtotal the discount applies to

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

PredictedPackage

NameTypeDescription
heightnumberHeight of a predicted package
widthnumberWidth of a predicted package
lengthnumberLength of a predicted package
weightnumberTotal weight of a predicted package
declaredValuenumberDeclared value of a predicted package (subtotal of items in package)

ShippingAddressInfo

NameTypeDescription
streetstringCustomer’s street
citystringCustomer’s city
countryCodestringCustomer’s country code in Ecwid
countryNamestringCustomer’s country name in Ecwid
postalCodestringCustomer’s postal code
stateOrProvinceCodestringCustomer’s state or province code in Ecwid
stateOrProvinceNamestringCustomer’s state or province name in Ecwid

OriginAdressInfo

NameTypeDescription
streetstringCustomer’s street
citystringCustomer’s city
countryCodestringCustomer’s country code in Ecwid
postalCodestringCustomer’s postal code
stateOrProvinceCodestringCustomer’s state or province code in Ecwid

HandlingFeeInfo

FieldTypeDescription
namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer

Response

Response to Ecwid example

{
    "shippingOptions": [{
        "title": "SuperMail First Class",
        "rate": 10.31,
        "transitDays": "2-7"
    }, {
        "title": "SuperMail Regular Delivery",
        "rate": 5.01,
        "transitDays": "5"
    }]
}

An array of JSON data of type 'ShippingOptions’ with the following fields:

ShippingOptions

NameTypeDescription
titlestringShipping method name
ratenumberShipping rate amount
transitDaysstringEstimated delivery time. Formats accepted: empty "", number "5", several days estimate "4-9"

Weight units

Ecwid supports several weigh units that can be passed in the request to your application to provide shipping rates. Below you can see all available units as well as their conversion values for calculation.

NameCodeValue
Caratcarat0.2
Gramgram1
Ounceounce28.35
Poundlbs453.6
Kilogramkg1000

Gram is the main weight unit, from which other units are converted. Merchants can change weight units in Ecwid Control Panel.