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,
        "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": 1.2,
                "price": 2,
                "amount": 1,
                "productId": 65955001,
                "name": "Apple",
                "categoryId": 19175294,
                "sku": "30022537",
                "selectedOptions": [
                    {
                        "name": "Box type",
                        "value": "Big",
                        "valuesArray": [
                            "Big"
                        ]
                    }
                ],
                "dimensions": {
                    "height": 3.5,
                    "width": 6,
                    "length": 12.5
                }
            },
            {
                "weight": 0.3,
                "price": 5.08,
                "amount": 1,
                "productId": 66568001,
                "name": "Orange",
                "categoryId": 19175294,
                "sku": "02266183",
                "selectedOptions": null,
                "dimensions": {
                    "height": 0,
                    "width": 0,
                    "length": 0
                }
            }
        ],
        "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"
    }
}
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

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 combination, this will be a combination SKU.
amountnumberAmount purchased
namestringProduct name
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
dimensions<ProductDimensions>Product dimensions info

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

ProductDimensions

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

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

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.