NAV

Orders

The endpoints below allow you to search/create/update/delete orders in an Ecwid store. Learn more about orders in Ecwid in our Help Center.

Search orders

Search or filter orders in an Ecwid store. The response provides full details of the found orders.

Request example

GET /api/v3/4870020/orders?customer=johnsmith@example.com&paymentStatus=PAID,AWAITING_PAYMENT&token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders?keywords={keywords}&totalFrom={totalFrom}&totalTo={totalTo}&createdFrom={createdFrom}&createdTo={createdTo}&updatedFrom={updatedFrom}&updatedTo={updatedTo}&couponCode={couponCode}&orderNumber={orderNumber}&vendorOrderNumber={vendorOrderNumber}&customer={customer}&paymentMethod={paymentMethod}&shippingMethod={shippingMethod}&paymentStatus={paymentStatus}&fulfillmentStatus={fulfillmentStatus}&offset={offset}&limit={limit}&token={token}

Q: How to get info about abandoned sales?

To get abandoned sale information, specify INCOMPLETE for paymentStatus filter when searching for orders. Also, check out the carts endpoint methods for additional info.

Coming soon: Abandoned sales will not have an orderNumber or vendorOrderNumber assigned to them. Instead, they will have a unique order id in orderNumber and vendorOrderNumber field.

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 100
keywordsstringSearch term. Ecwid will look for this term in order number, ordered items and customer details.
couponCodenumberThe code of coupon applied to order
totalFromnumberMinimum product price
totalTonumberMaximum product price
orderNumbernumberOrder number(s) separated by a comma. If this field is not empty, other filters are ignored
vendorOrderNumberstringOrder number with prefix/suffix defined by admin
customerstringCustomer search term. Searches for customer details in order, except for customerId
createdFromstringOrder placement date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
Examples:
  • 1447804800
  • 2015-04-22 18:48:38 -0500
  • 2015-04-22 (this is 2015-04-22 00:00:00 UTC)
createdTostringOrder placement date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedFromstringOrder last update date/time (lower bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
updatedTostringOrder last update date/time (upper bound). Supported formats:
  • UNIX timestamp
  • yyyy-MM-dd HH:mm:ss Z
  • yyyy-MM-dd HH:mm:ss
  • yyyy-MM-dd
paymentMethodstringPayment method used by customer
shippingMethodstringShipping method chosen by customer
paymentStatusstringComma separated list of order payment statuses to search. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringComma separated list of order fulfilment statuses to search. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP

Response

Response example (JSON)

{
    "total": 1,
    "count": 1,
    "offset": 0,
    "limit": 100,
    "items": [
        {
            // Basic information
            "vendorOrderNumber": "20",
            "orderNumber": 20,
            "tax": 1.79,
            "subtotal": 29.95,
            "total": 37.39,
            "usdTotal": 37.39,
            "paymentMethod": "Purchase order",
            "paymentStatus": "PAID",
            "fulfillmentStatus": "AWAITING_PROCESSING",

            // Additional information
            "refererUrl": "http://mysuperstore.ecwid.com/",
            "globalReferer": "",
            "createDate": "2014-09-20 19:59:43 +0000",
            "updateDate": "2014-09-21 00:00:12 +0000",
            "createTimestamp": 1427268654,
            "updateTimestamp": 1427272209,
            "hidden": false,
            "orderComments": "Test order comments",
            "privateAdminNotes": "Must be delivered till Sunday.",

            // Basic customer information
            "email": "johnsmith@example.com",
            "ipAddress": "83.217.8.241",
            "customerId": 15319410,
            "customerGroupId": 12345,
            "customerGroup": "Gold",
            "customerTaxExempt": false,
            "customerTaxId": "",
            "customerTaxIdValid": false,
            "reversedTaxApplied": false,

            // Discounts in order
            "membershipBasedDiscount": 0,
            "totalAndMembershipBasedDiscount": 2.85,
            "couponDiscount": 1.5,
            "discount": 2.85,
            "volumeDiscount": 0,
            "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": [
                {
                    "value": 10,
                    "type": "PERCENT",
                    "base": "ON_TOTAL_AND_MEMBERSHIP",
                    "orderTotal": 15
                },
                {
                    "value": 2,
                    "type": "ABSOLUTE",
                    "base": "CUSTOM",
                    "description": "Buy more than 3 cherries and get $2 off!"
                }
            ],

            // Order items details
            "items": [
                {
                    "id": 40989227,
                    "productId": 37208342,
                    "categoryId": 9691094,
                    "price": 5.99,
                    "productPrice": 5.99,
                    "weight": 0.32,
                    "sku": "00004",
                    "quantity": 5,
                    "shortDescription": "Cherry\nThe word cherry refers to a fleshy fruit (drupe) that contains a single stony seed. The cherry belongs to the fa...",
                    "tax": 1.79,
                    "shipping": 10,
                    "quantityInStock": 1981,
                    "name": "Cherry",
                    "isShippingRequired": true,
                    "trackQuantity": true,
                    "fixedShippingRateOnly": false,
                    "imageUrl": "http://app.ecwid.com/default-store/00006-sq.jpg",
                    "fixedShippingRate": 1,
                    "digital": true,
                    "productAvailable": true,
                    "couponApplied": false,
                    "files": [
                        {
                            "productFileId": 7215101,
                            "maxDownloads": 0,
                            "remainingDownloads": 0,
                            "expire": "2014-10-26 20:34:34 +0000",
                            "name": "myfile.jpg",
                            "description": "Sunflower",
                            "size": 54492,
                            "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101?token=123123123",
                            "customerUrl": "http://mysuperstore.ecwid.com/download/4870020/a2678e7d1d1c557c804c37e4/myfile.jpg"
                        }
                    ],
                    "selectedOptions": [
                        {
                            "name": "Size",
                            "value": "Big",
                            "valuesArray" : [
                              "Big"
                            ],
                            "type": "CHOICE"
                        },
                        {
                            "name": "Attach a file",
                            "type": "FILES",
                            "files": [
                                {
                                    "id": 5973037,
                                    "name": "makfruit_ava_sunnyflower_200_200.jpg",
                                    "size": 54492,
                                    "url": "https://app.ecwid.com/orderfile/4870020/5973037/54492/makfruit_ava_sunnyflower_200_200.jpg"
                                }
                            ]
                        },
                        {
                            "name": "Choose date",
                            "value": "2014-09-10",
                            "type": "DATE"
                        },
                        {
                            "name": "Any text",
                            "value": "Test text",
                            "type": "TEXT"
                        }
                    ],
                    "taxes": [
                        {
                            "name": "Tax X",
                            "value": 7,
                            "total": 1.79,
                            "taxOnDiscountedSubtotal": 1.79,
                            "taxOnShipping": 0
                        }
                    ],
                    "productDimensions": {
                        "length": 34,
                        "width": 3,
                        "height": 22
                    }
                }
            ],

            // Customer addresses
            "billingPerson": {
                "name": "John Smith",
                "companyName": "Unreal Company",
                "street": "W 3d st",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10001",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": "+1234567890"
            },
            "shippingPerson": {
                "name": "John Smith",
                "companyName": "Unreal Company",
                "street": "W 3d st",
                "city": "New York",
                "countryCode": "US",
                "countryName": "United States",
                "postalCode": "10001",
                "stateOrProvinceCode": "NY",
                "stateOrProvinceName": "New York",
                "phone": "+1234567890"
            },

            // Shipping information
            "shippingOption": {
                "shippingMethodName": "2nd day delivery",
                "shippingRate": 10,
                "estimatedTransitTime": "5",
                "isPickup": false,
                "pickupInstruction": ""
            },
            "handlingFee": {
                "name": "Wrapping",
                "value": 2,
                "description": "Silk paper wrapping"
            },
            "predictedPackages":[  
                {  
                    "length":34,
                    "width":3,
                    "height":22,
                    "weight":0.32,
                    "declaredValue":29.95
                }
            ],

            // Other information
            "additionalInfo": {},
            "paymentParams": {
                "Company name": "Unreal Company",
                "Job position": "Manager",
                "PO number": "123abcd",
                "Buyer's full name": "John Smith"
            }
        }
    ]
}

A JSON object of type ‘SearchResult’ with the following fields:

SearchResult

FieldTypeDescription
totalnumberThe total number of found items (might be more than the number of returned items)
countnumberThe total number of the items returned in this batch
offsetnumberOffset from the beginning of the returned items list (for paging)
limitnumberMaximum number of returned items. Maximum allowed value: 100. Default value: 10
itemsArray<OrderEntry>The items list

OrderEntry

FieldTypeDescription
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique order ID.
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique order ID.
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidbooleantrue if customer tax ID is valid, false otherwise
reversedTaxAppliedbooleantrue if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
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)
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unsfinished orders only.
usdTotalnumberOrder total in USD
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
updateDatedateThe date/time of the last order change, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberThe date of the last order change in UNIX Timestamp format, e.g 1427268654
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
predictedPackages<PredictedPackage>Predicted information about the package to ship items in to customer
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
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
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
productAvailablebooleantrue/false: shows whether the product is available in the store
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
filesArray<OrderItemProductFile>Files attached to the order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

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

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name
phonestringPhone number

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

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”
isPickupbooleantrue if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

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)

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Errors

Error response example

HTTP/1.1 500 Server Error
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get order details

Get all available information about an order referring to its ID. The order details include: customer email, payment/shipping method, items purchased and more.

Q: How can I request details of several orders at once?

When you know the exact order numbers for orders you need, you can get those order details in one request (batch request). To do that, use the Search orders method: provide the order numbers you have in the orderNumber parameter separating them with a comma.

This way your app will save some time as you will be performing less requests to the Ecwid API and they will be much more efficient.

Request example

GET /api/v3/4870020/orders/20?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber

Response

Response example (JSON)

{
    // Basic information
    "vendorOrderNumber": "20",
    "orderNumber": 20,
    "tax": 1.79,
    "subtotal": 29.95,
    "total": 37.39,
    "usdTotal": 37.39,
    "paymentMethod": "Purchase order",
    "paymentStatus": "PAID",
    "fulfillmentStatus": "AWAITING_PROCESSING",

    // Additional information
    "refererUrl": "http://mysuperstore.ecwid.com/",
    "globalReferer": "",
    "createDate": "2014-09-20 19:59:43 +0000",
    "updateDate": "2014-09-21 00:00:12 +0000",
    "createTimestamp": 1427268654,
    "updateTimestamp": 1427272209,
    "hidden": false,
    "orderComments": "Test order comments",
    "privateAdminNotes": "Must be delivered till Sunday.",

    // Basic customer information
    "email": "johnsmith@example.com",
    "ipAddress": "83.217.8.241",
    "customerId": 15319410,
    "customerGroupId": 12345,
    "customerGroup": "Gold",
    "customerTaxExempt": false,
    "customerTaxId": "",
    "customerTaxIdValid": false,
    "reversedTaxApplied": false,    

    // Discounts in order
    "membershipBasedDiscount": 0,
    "totalAndMembershipBasedDiscount": 2.85,
    "couponDiscount": 1.5,
    "discount": 2.85,
    "volumeDiscount": 0,
    "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": [
        {
            "value": 10,
            "type": "PERCENT",
            "base": "ON_TOTAL_AND_MEMBERSHIP",
            "orderTotal": 15
        }
    ],

    // Order items details
    "items": [
        {
            "id": 40989227,
            "productId": 37208342,
            "categoryId": 9691094,
            "price": 5.99,
            "productPrice": 5.99,
            "weight": 0.32,
            "sku": "00004",
            "quantity": 5,
            "shortDescription": "Cherry\nThe word cherry refers to a fleshy fruit (drupe) that contains a single stony seed. The cherry belongs to the fa...",
            "tax": 1.79,
            "shipping": 10,
            "quantityInStock": 1981,
            "name": "Cherry",
            "isShippingRequired": true,
            "trackQuantity": true,
            "fixedShippingRateOnly": false,
            "imageUrl": "http://app.ecwid.com/default-store/00006-sq.jpg",
            "fixedShippingRate": 1,
            "digital": true,
            "productAvailable": true,
            "couponApplied": false,
            "files": [
                {
                    "productFileId": 7215101,
                    "maxDownloads": 0,
                    "remainingDownloads": 0,
                    "expire": "2014-10-26 20:34:34 +0000",
                    "name": "myfile.jpg",
                    "description": "Sunflower",
                    "size": 54492,
                    "adminUrl": "https://app.ecwid.com/api/v3/4870020/products/37208340/files/7215101?token=123123123",
                    "customerUrl": "http://mysuperstore.ecwid.com/download/4870020/a2678e7d1d1c557c804c37e4/myfile.jpg"
                }
            ],
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Big",
                    "valuesArray" : [
                      "Big"
                    ],
                    "type": "CHOICE"
                },
                {
                    "name": "Attach a file",
                    "type": "FILES",
                    "files": [
                        {
                            "id": 5973037,
                            "name": "makfruit_ava_sunnyflower_200_200.jpg",
                            "size": 54492,
                            "url": "https://app.ecwid.com/orderfile/4870020/5973037/54492/makfruit_ava_sunnyflower_200_200.jpg"
                        }
                    ]
                },
                {
                    "name": "Choose date",
                    "value": "2014-09-10",
                    "type": "DATE"
                },
                {
                    "name": "Any text",
                    "value": "Test text",
                    "type": "TEXT"
                }
            ],
            "taxes": [
                {
                    "name": "Tax X",
                    "value": 7,
                    "total": 1.79,
                    "taxOnDiscountedSubtotal": 1.79,
                    "taxOnShipping": 0
                }
            ],
            "productDimensions": {
                "length": 34,
                "width": 3,
                "height": 22
            }
        }
    ],

    // Customer addresses
    "billingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },
    "shippingPerson": {
        "name": "John Smith",
        "companyName": "Unreal Company",
        "street": "W 3d st",
        "city": "New York",
        "countryCode": "US",
        "countryName": "United States",
        "postalCode": "10001",
        "stateOrProvinceCode": "NY",
        "stateOrProvinceName": "New York",
        "phone": "+1234567890"
    },

    // Shipping information
    "shippingOption": {
        "shippingMethodName": "2nd day delivery",
        "shippingRate": 10,
        "estimatedTransitTime": "5"
    },
    "handlingFee": {
        "name": "Wrapping",
        "value": 2,
        "description": "Silk paper wrapping"
    },
    "predictedPackages":[  
        {  
            "length":34,
            "width":3,
            "height":22,
            "weight":0.32,
            "declaredValue":29.95
        }
    ],

    // Other information
    "additionalInfo": {},
    "paymentParams": {
        "Company name": "Unreal Company",
        "Job position": "Manager",
        "PO number": "123abcd",
        "Buyer's full name": "John Smith"
    }
}

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
orderNumbernumberUnique order number without prefixes/suffixes, e.g. 34. COMING SOON: For completed orders orderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, orderNumber will be a unique order ID.
vendorOrderNumberstringOrder number with prefix and suffix defined by admin, e.g. ABC34-q. COMING SOON: For completed orders, vendorOrderNumber will work as usual. For abandoned sales i.e. the paymentStatus is INCOMPLETE, vendorOrderNumber will be a unique order ID.
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidbooleantrue if customer tax ID is valid, false otherwise
reversedTaxAppliedbooleantrue if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
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
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
usdTotalnumberOrder total in USD
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
updateDatedateThe date/time of the last order change, e.g 2014-06-06 18:57:19 +0000
createTimestampnumberThe date of order placement in UNIX Timestamp format, e.g 1427268654
updateTimestampnumberThe date of the last order change in UNIX Timestamp format, e.g 1427268654
customerGroupIdnumberCustomer group ID
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
predictedPackages<PredictedPackage>Predicted information about the package to ship items in to customer
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID. Can be used to address the item in the order, e.g. to manage ordered items.
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
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU. If the chosen options match a combination, this will be a combination SKU.
quantitynumberAmount purchased
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
namestringProduct name
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
imageUrlstringProduct image URL
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
productAvailablebooleantrue/false: shows whether the product is available in the store
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
filesArray<OrderItemProductFile>Files attached to the order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
taxOnDiscountedSubtotalnumberTax on item subtotal (after applying discounts)
taxOnShippingnumberTax on item shipping

OrderItemProductFile

FieldTypeDescription
productFileIdnumberInternal unique file ID
maxDownloadsnumberMax allowed number of file downloads. See E-goods article in Ecwid Help center for the details
remainingDownloadsnumberRemaining number of download attempts
expirestringDate/time of the customer download link expiration
namestringFile name
descriptionstringFile description defined by the store administrator
sizenumberFile size, bytes (64-bit integer)
adminUrlstringLink to the file. Be careful: the link contains the API access token. Make sure you do not display the link as is in your application and not give it to a customer.
customerUrlstringFile download link that is sent to the customer when the order is paid

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

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
countryNamestringCountry name
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
stateOrProvinceNamestringState/province name, e.g. New York
phonestringPhone number

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

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Possible formats: number “5”, several days estimate “4-9”
isPickupbooleantrue if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

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)

DiscountInfo

FieldTypeDescription
valuenumberDiscount value
typestringDiscount type: ABS or PERCENT
basestringDiscount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM
orderTotalnumberMinimum order subtotal the discount applies to
descriptionstringDescription of a discount (for discounts with base == CUSTOM)

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order is not found
405Method not allowed. Can occur when using POST instead of PUT HTTP request method
415Unsupported content-type: expected application/json or text/json
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Get order invoice

Get HTML code of an invoice for a specific order placed in an Ecwid store.

Request example

GET /api/v3/4870020/orders/20/invoice?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

GET https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/invoice?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber

Response

Response example (HTML)

<!DOCTYPE html>
<html>
    <head>
        <title>Order - #ab645ad</title>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <meta http-equiv="X-UA-Compatible" content="IE=Edge">
        <script>
        function printFrame() {
            window.document.close();
            window.focus();
            window.print();
            setTimeout(function(){window.close();}, 1);
        }
    </script>
    </head>
    <body onload="printFrame()">
        <!-- Invoice styles -->
        <style type="text/css">
html,body {
    min-height:50%;
    margin:0;
    padding:0;
}

body {
    background-color:#fff;
    width:210mm;
    -moz-box-sizing:border-box;
    box-sizing:border-box;
    padding:20mm 10mm 15mm;
}

body > div {
    height:100%;
}

body p:empty {
    display:none;
}

body a {
    text-decoration:none;
    color:#000;
}

body table {
    border-collapse:collapse;
    border-spacing:0;
}

body .body {
    height:100%;
    width:130mm;
    margin:0 auto;
}

body .body td {
    vertical-align:top;
    height:0;
    font-family:Arial, Helvetica, "Sans Serif";
    font-size:8pt;
    line-height:10pt;
    color:#000;
    padding:0;
}

body .body td.footer {
    height:100%;
    text-align:center;
    vertical-align:bottom;
}

body .body td.footer div {
    border-bottom:1px solid #000;
    padding:10mm 0 5pt;
}

body .body .invoice td td {
    vertical-align:top;
    padding:0;
}

body .body .invoice p {
    margin:2pt 0;
}

body .body .invoice .store-info {
    width:100%;
    margin-bottom:16pt;
}

body .body .invoice .store-info .invoice-logo {
    max-height:25mm;
    max-width:100%;
    width:auto;
    display:block;
    margin:0 0 5mm;
}

body .body .invoice .store-info .store-title {
    font-size:10pt;
    line-height:12pt;
    font-weight:600;
    padding:5pt 0;
}

body .body .invoice .store-info .store-main-info {
    width:89mm;
    padding-right:5mm;
}

body .body .invoice .store-info .store-main-info .title-detached {
    margin-top:5pt;
    margin-bottom:5pt;
}


body .body .invoice .store-info .store-customer-info {
    vertical-align:top;
}

body .body .invoice .store-info .store-customer-info p {
    max-width:60mm;
    word-wrap:break-word;
}

body .body .invoice td.invoice-row,body .body .invoice .invoice-row > tr:first-child > td {
    border-top:1px solid #000;
}

body .body .invoice .order-comment {
    padding-bottom: 12pt;
}

body .body .invoice .order-info {
    margin-bottom:11pt;
    padding:0;
}

body .body .invoice .order-items {
    margin-bottom:16pt;
    padding:0;
}

body .body .invoice .order-info td,body .body .invoice .order-items td {
    width:42mm;
    padding-right:5mm;
}

body .body .invoice .order-info td:last-child,body .body .invoice .order-items td:last-child {
    width:auto;
}

body .body .invoice .order-info .title,body .body .invoice .order-items .title {
    font-weight:600;
    padding-top:5pt;
    padding-bottom:12pt;
    margin:0;
}

body .body .invoice .order-info td:last-child {
    padding-right:0;
}

body .body .invoice .order-info p {
    max-width:42mm;
    word-wrap:break-word;
}

body .body .invoice .order-info .order-comment p {
    max-width: 100%;
    word-break: break-all;
    white-space: pre-wrap;
}

body .body .invoice .order-comment-title {
    margin-bottom: 4pt; 
}

body .body .invoice .order-items table tbody tr:last-child td {
    padding-bottom:3pt;
}

body .body .invoice .order-items .title {
    padding-bottom:5pt;
}

body .body .invoice .order-items .order-item-desc {
    width:87mm;
}

body .body .invoice .order-items .order-item-count {
    width:11mm;
}

body .body .invoice .order-items .order-item-count,body .body .invoice .order-items .order-item-total {
    text-align:right;
    padding-right:1mm;
}

body .body .invoice .order-items .order-item-total {
    padding-right:2mm;
    white-space: nowrap;
}

body .body .invoice .order-items .order-total td {
    padding-top:1pt;
    padding-bottom:1pt;
}

body .body .invoice,body .body .invoice .order-items table {
    width:100%;
}

body .body .invoice td,body .body .invoice .order-items table td {
    padding:0 1mm;
}

body .body .invoice .text-uppercase,body .body .invoice .order-info .title::first-letter,body .body .invoice .order-items .title::first-letter {
    text-transform:uppercase;
}

body .body .invoice .text-bold,body .body .invoice .order-items .order-item-title {
    font-weight:600;
}

body .body .invoice .store-info .store-main-info .url,body .body .invoice .order-info .title-detached,body .body .invoice .order-items .title-detached {
    margin-bottom:5pt;
}

body .body .invoice .store-info .store-main-info p,body .body .invoice .order-items .order-item-desc p {
    max-width:87mm;
    word-wrap:break-word;
}

body .body .invoice .order-items .order-item-desc .order-discount-coupon {
    max-width: 64mm;
}

body .body .invoice .order-items table tbody tr td,body .body .invoice .order-items .order-total tr:first-child td {
    padding-top:7pt;
}

@media print{
    * {
        -webkit-print-color-adjust:exact;
    }

    html,body {
        height:100%;
    }

    body {
        padding:0;
    }

    @page {
        margin:20mm 0 15mm;
    }
}
</style>
        <!-- Invoice body markup -->
        <table class="body">
            <tbody>
                <tr>
                    <td>
                        <table class="invoice">
                            <tbody>
                                <!-- Your company information -->
                                <tr>
                                    <td>
                                        <table class="store-info">
                                            <thead>
                                                <!-- Invoice logo -->
                                                <tr>
                                                    <td colspan="2" class="store-title">
                                                        <!-- Store name -->
                                                        <span>Awesome store</span>
                                                    </td>
                                                </tr>
                                            </thead>
                                            <tbody>
                                                <tr>
                                                    <!-- Company information: store URL, tax ID, company name, address and contact information -->
                                                    <td class="store-main-info">
                                                        <p class="url">    superstore.com
</p>
                                                        <p class="title-detached">Tax registration ID: 1234567</p>
                                                        <p>Cool slippers for dogs</p>
                                                        <p>5th Avenue</p>
                                                        <p>New York, NY 10002</p>
                                                        <p>United States</p>
                                                    </td>
                                                    <td class="store-customer-info">
                                                        <p>
                                                            <b>Customer service</b>
                                                        </p>
                                                        <p></p>
                                                        <p>info@superstore.com</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                                <!-- Shipping and billing information -->
                                <tr>
                                    <td class="invoice-row">
                                        <table class="order-info">
                                            <thead>
                                                <tr>
                                                    <!-- Order date -->
                                                    <td colspan="2" class="title">
                                                        <span>Fri, Jun 3, '16</span>
                                                    </td>
                                                </tr>
                                            </thead>
                                            <tbody>
                                                <tr>
                                                    <!-- Customer shipping address -->
                                                    <!-- Customer billing address -->
                                                    <td>
                                                        <p class="text-uppercase">s</p>
                                                        <p></p>
                                                        <p>Mark Cool</p>
                                                        <p>New York, New York, NY</p>
                                                        <p>United States</p>
                                                        <p></p>
                                                        <p>customer@gmail.com</p>
                                                    </td>
                                                    <td>
                                                        <!-- Shipping option chosen to deliver the order -->
                                                        <p>Shipped via Ground Delivery</p>
                                                        <!-- Payment option that customer used to pay for the order -->
                                                        <p>Payment method PayPal</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                                <!-- Order comments -->
                                <!-- Order information -->
                                <tr>
                                    <td class="order-items">
                                        <table>
                                            <tbody class="invoice-row">
                                                <tr>
                                                    <td colspan="3" class="title">
                                                        <!-- Order number -->
                                                        <span>Order #ab645ad</span>
                                                    </td>
                                                </tr>
                                                <!-- Ordered items list -->
                                                <tr>
                                                    <td class="order-item-desc">
                                                        <p class="order-item-title">Galaxy SII</p>
                                                        <p>SKU : 000026</p>
                                                    </td>
                                                    <td class="order-item-count">
                                                        <p>1</p>
                                                    </td>
                                                    <td class="order-item-total text-bold">
                                                        <p>$100</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                            <!-- Order totals -->
                                            <tbody class="invoice-row order-total">
                                                <!-- Order subtotal -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Items</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>$100</p>
                                                    </td>
                                                </tr>
                                                <!-- Order shipping cost -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Shipping</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>$10</p>
                                                    </td>
                                                </tr>
                                                <!-- Order handling fee cost -->
                                                <!-- Order tax -->
                                                <!-- Order discounts total -->
                                                <tr>
                                                    <td colspan="2" class="order-item-count">
                                                        <p>Discount</p>
                                                    </td>
                                                    <td class="order-item-total">
                                                        <p>-$14</p>
                                                    </td>
                                                </tr>
                                                <!-- Order total cost -->
                                                <tr>
                                                    <td class="order-item-desc"></td>
                                                    <td class="order-item-count text-bold">
                                                        <p>Total</p>
                                                    </td>
                                                    <td class="order-item-total text-bold">
                                                        <p>$96</p>
                                                    </td>
                                                </tr>
                                            </tbody>
                                        </table>
                                    </td>
                                </tr>
                            </tbody>
                        </table>
                    </td>
                </tr>
                <!-- Invoice footer -->
                <tr>
                    <td class="footer">
                        <div>Thank you for your order!</div>
                    </td>
                </tr>
            </tbody>
        </table>
    </body>
</html>

HTML code of an invoice for the requested order number.

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order is not found
405Method not allowed. Can occur when using PUT/POST/DELETE HTTP request methods instead of GET
415Unsupported content-type: expected application/json or text/json
422Cannot generate an invoice for unfinished order
500Cannot retrieve the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Update order

This request allows you to update existing orders in an Ecwid store. When updating order information, you can omit unchanged fields – they will be ignored so the resulting order will keep the corresponding information unchanged.

However, please mind that if you want to update the ordered items, you should submit all the items in the request. The omitted items will be removed. This is done this way to let you remove some purchased items from the order.

Request example

PUT /api/v3/4870020/orders/20?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
        "subtotal": 35,
        "total": 45,
        "email": "newemail@example.com",
        "paymentMethod": "New payment method",
        "tax": 0,
        "paymentStatus": "CANCELLED",
        "fulfillmentStatus": "PROCESSING",
        "customerTaxExempt": false,
        "customerTaxId": "",
        "customerTaxIdValid": false,
        "reversedTaxApplied": false,
        "billingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingOption": {
            "shippingMethodName": "Fast Delivery",
            "shippingRate": 10
        },
        "items": [
            {
                "id": 41056225,
                "productId": 37208346,
                "price": 7.99,
                "productPrice": 7.99,
                "weight": 0.31,
                "sku": "00001",
                "quantity": 5,
                "shortDescription": "New description",
                "tax": 1.79,
                "shipping": 10,
                "quantityInStock": 1981,
                "name": "New name",
                "isShippingRequired": true,
                "fixedShippingRateOnly": false,
                "productAvailable": true,
                "selectedOptions": [
                    {
                        "name": "Size",
                        "value": "Big",
                        "type": "CHOICE"
                    },                  
                    {
                        "name": "Any text",
                        "value": "Test text",
                        "type": "TEXT"
                    }
                ],
                "taxes": [
                    {
                        "name": "Tax Y",
                        "value": 7,
                        "total": 4.79
                    }
                ],
                "productDimensions": {
                    "length": 34,
                    "width": 3,
                    "height": 22
                }
            }
        ],
        "hidden": false,
        "privateAdminNotes": "Must be delivered till Sunday."
    }

PUT https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber for completed orders. Coming soon: you can also use order id you got from the order details in the orderNumber field for abandoned sales (paymentStatus == INCOMPLETE).

Request body

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidbooleantrue if customer tax ID is valid, false otherwise
reversedTaxAppliedbooleantrue if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
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
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
globalRefererstringURL that the customer came to the store from
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner

OrderItem

FieldTypeDescription
idnumberOrder item ID.
quantitynumberAmount purchased
namestringProduct name
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
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct/Combination SKU
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
productAvailablebooleantrue/false: shows whether the product is available in the store
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item

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 value by customer. Multiple values separated by comma in a single string
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
phonestringPhone number

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

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Formats accepted: number “5”, several days estimate “4-9”
isPickupbooleantrue if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

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

DiscountInfo

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

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Response

Response example (JSON)

{
    "updateCount": 1
}

A JSON object of type 'UpdateStatus’ with the following fields:

UpdateStatus

FieldTypeDescription
updateCountnumberThe number of updated orders (1 or 0 depending on whether the update was successful)

Errors

Error response example

HTTP/1.1 400 Status QUEUED is deprecated, use AWAITING_PAYMENT instead
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are invalid
404The order is not found
415Unsupported content-type: expected application/json or text/json
500Cannot update the order info because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete order

Delete a specific order in an Ecwid store referrint to its ID.

Request example

DELETE /api/v3/4870020/orders/20?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted orders (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description.

HTTP codes

HTTP StatusMeaning
400Request parameters are malformed
404The order with given number is not found
500The delete request failed because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Create order

Request example

POST /api/v3/4870020/orders?token=1234567890qwqeertt HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json;charset=utf-8
Cache-Control: no-cache

{
        "subtotal": 30,
        "total": 40,
        "email": "example@example.com",
        "paymentMethod": "Phone order",
        "tax": 0,
        "paymentStatus": "PAID",
        "customerTaxExempt": false,
        "customerTaxId": "",
        "customerTaxIdValid": false,
        "reversedTaxApplied": false,
        "fulfillmentStatus": "AWAITING_PROCESSING",
        "createDate": "2015-09-20 19:59:43 +0000",
        "items": [
            {
                "price": 15,
                "weight": 0.32,
                "sku": "00004",
                "quantity": 2,
                "name": "Cherry"
            }
        ],
        "billingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingPerson": {
            "name": "Eugene K",
            "companyName": "Hedgehog and Bucket",
            "street": "My Street",
            "city": "San Diego",
            "countryCode": "US",
            "postalCode": "90002",
            "stateOrProvinceCode": "CA",
            "phone": "123141321"
        },
        "shippingOption": {
            "shippingMethodName": "Fast Delivery",
            "shippingRate": 10
        },
        "hidden": false,
        "privateAdminNotes": "Must be delivered till Sunday."
    }

POST https://app.ecwid.com/api/v3/{storeId}/orders?token={token}

FieldTypeDescription
storeIdnumberEcwid store ID
tokenstringoAuth token

Create a new order in an Ecwid store. This can be useful for storefronts with a custom checkout process or manually creating orders for sales made earlier.

Request body

A JSON object of type 'Order’ with the following fields:

Order

FieldTypeDescription
subtotalnumberOrder subtotal. Includes the sum of all products’ cost in the order
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total
customerTaxExemptbooleantrue if customer is tax exempt, false otherwise. Learn more
customerTaxIdstringCustomer tax ID
customerTaxIdValidbooleantrue if customer tax ID is valid, false otherwise
reversedTaxAppliedbooleantrue if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise
ipAddressstringCustomer IP
couponDiscountnumberDiscount applied to order using a coupon
paymentStatusstringPayment status. Supported values:
  • AWAITING_PAYMENT
  • PAID
  • CANCELLED
  • REFUNDED
  • PARTIALLY_REFUNDED
  • INCOMPLETE
. Ignored when creating orders with public token
fulfillmentStatusstringFulfilment status. Supported values:
  • AWAITING_PROCESSING
  • PROCESSING
  • SHIPPED
  • DELIVERED
  • WILL_NOT_DELIVER
  • RETURNED
  • READY_FOR_PICKUP
. Ignored when creating orders with public token
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringOrder comments
volumeDiscountnumberSum of discounts based on subtotal. Is included into the discount field
customerIdnumberUnique customer internal ID (if the order is placed by a registered user)
hiddenbooleanDetermines if the order is hidden (removed from the list). Applies to unfinished orders only.
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
discountnumberThe sum of applied discounts without coupon discount.
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2014-06-06 18:57:19 +0000
customerGroupstringThe name of group (membership) the customer belongs to
discountCoupon<DiscountCouponInfo>Information about applied coupon
itemsArray<OrderItem>Order items
billingPerson<PersonInfo>Name and billing address of the customer
shippingPerson<PersonInfo>Name and address of the person entered in shipping information
shippingOption<ShippingOptionInfo>Information about selected shipping option
handlingFee<HandlingFeeInfo>Handling fee details
additionalInfoMap<string,string>Additional order information if any (reserved for future use)
paymentParamsMap<string,string>Additional payment parameters entered by customer on checkout, e.g. PO number in “Purchase order” payments
discountInfoArray<DiscountInfo>Information about applied discounts (coupons are not included)
trackingNumberstringShipping tracking code
paymentMessagestringMessage from the payment processor if any
externalTransactionIdstringTransaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID)
affiliateIdstringAffiliate ID
creditCardStatus<CreditCardStatus>The status of credit card payment
privateAdminNotesstringPrivate note about the order from store owner. Ignored when creating orders with public token

OrderItem

FieldTypeDescription
namestringProduct name
quantitynumberAmount purchased
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
productPricenumberBasic product price without options markups, wholesale discounts etc.
weightnumberProduct weight
skustringProduct SKU
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
shippingnumberOrder item shipping cost
quantityInStocknumberThe number of products in stock in the store
isShippingRequiredbooleantrue/false: shows whether the item requires shipping
trackQuantitybooleantrue/false: shows whether the store admin set to track the quantity of this product and get low stock notifications
fixedShippingRateOnlybooleantrue/false: shows whether the fixed shipping rate is set for the product
fixedShippingRatenumberFixed shipping rate for the product
digitalbooleantrue/false: shows whether the item has downloadable files attached
productAvailablebooleantrue/false: shows whether the product is available in the store
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer
taxesArray<OrderItemTax>Taxes applied to this order item
productDimensions<ProductDimensions>Product dimensions info

OrderItemTax

FieldTypeDescription
namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item

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 value by customer. Multiple values separated by comma in a single string
filesArray<OrderItemOptionFile>Attached files (if the option type is FILES)

ProductDimensions

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

PersonInfo

FieldTypeDescription
namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by ’\n’
citystringCity
countryCodestringTwo-letter country code
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY
phonestringPhone number

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

DiscountCouponCatalogLimit

FieldTypeDescription
productsArray<number>The list of product IDs the coupon can be applied to
categoriesArray<number>The list of category IDs the coupon can be applied to

ShippingOptionInfo

FieldTypeDescription
shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodNamestringShipping option name
shippingRatenumberRate
estimatedTransitTimestringDelivery time estimation. Formats accepted: number “5”, several days estimate “4-9”
isPickupbooleantrue if selected shipping option is local pickup. false otherwise
pickupInstructionstringInstruction for customer on how to receive their products

HandlingFeeInfo

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

DiscountInfo

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

CreditCardStatus

FieldTypeDescription
avsMessagestringAddress verification status returned by the payment system.
cvvMessagestringCredit card verification status returned by the payment system.

Response

Response example (JSON)

{
    "id": 20
}

A JSON object of type 'CreateStatus’ with the following fields:

CreateStatus

FieldTypeDescription
idnumberThe number of created order in the store

Errors

Error response example

HTTP/1.1 400 Field OrderItem.quantity is absent
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusMeaning
400Request parameters are invalid
404The customer or any other linked object is not found in the store
500Cannot create an order because of an error on the server

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Upload item option file

Using this method, you can attach a file to an order item (implying that the order item has a 'file upload’ option). Request parameters specify which order, item and option should be updated. Request body is the file itself (binary data). Maximum allowed file size is 100Mb.

Request example

POST /api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

binary data

PHP Example

$file = file_get_contents('image.jpg');
$url = 'https://app.ecwid.com/api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd';

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,$url);
curl_setopt($ch, CURLOPT_POST,1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $file);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: image/jpeg;'));

$result = curl_exec($ch);
curl_close ($ch);

Python Example

import requests

request_url = "https://app.ecwid.com/api/v3/4870020/orders/20/items/987653/options/Attach+your+image?fileName=my_photo.jpg&token=123456789abcd"

image_file_data = open('image.jpg', 'rb').read()

result = requests.post(request_url,data=image_file_data)

print(result.status_code)

POST https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}?fileName={fileName}&token={token}&externalUrl={externalUrl}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
fileNamestringUploaded file name
tokenstringoAuth token
externalUrlstringExternal file URL available for public download. If specified, Ecwid will ignore any binary file data sent in a request

When uploading an item option file, the image itself needs to be sent in the body of your request in a form of binary data. The file that you wish to upload needs to be prepared for that format and then sent to Ecwid API endpoint.

Alternatively, you can specify an externalURL to your file as a request parameter and Ecwid will download it from there.

Response

Response example

{
    "id": 6005003
}

A JSON object of type 'UploadStatus’ with the following fields:

UploadStatus

FieldTypeDescription
idnumberInternal file ID

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescriptionCode (optional)
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
409Product option type is not FILESOPTIONS_IS_NOT_FILES_TYPE
413The file is too large. Maximum allowed file size is 100Mb.
415Unsupported content-type: expected application/octet-stream
500Uploading of the file failed or there was an internal server error while processing a file

Error response body (optional)

FieldTypeDescription
errorMessagestringError message

Delete item option file

Customers can attach files to product options when adding products to cart. Using this method, you can remove that file from an order.

Request example

DELETE /api/v3/4870020/orders/20/items/987653/options/Attach+your+image/files/1838839292388?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}/files/{fileId}?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
fileIdnumberOption file’s internal ID
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 1
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files (1 or 0 depending on whether the request was successful)

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
409Product option type is not FILES
500Request failed – there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code

Delete all item option’s files

Using this method, you can remove all files attached to an order item option by customer.

Request example

DELETE /api/v3/4870020/orders/20/items/987653/options/Attach+your+image/files?token=123456789abcd HTTP/1.1
Host: app.ecwid.com
Content-Type: application/json
Cache-Control: no-cache

DELETE https://app.ecwid.com/api/v3/{storeId}/orders/{orderNumber}/items/{itemId}/options/{optionName}/files?token={token}

NameTypeDescription
storeIdnumberEcwid store ID
orderNumbernumberOrder number. Make sure to use the orderNumber value here and not the vendorOrderNumber
itemIdnumberOrder item ID
optionNamestringItem product option name, e.g. Upload your photo
tokenstringoAuth token

Response

Response example

{
    "deleteCount": 2
}

A JSON object of type 'DeleteStatus’ with the following fields:

DeleteStatus

FieldTypeDescription
deleteCountnumberThe number of deleted files

Errors

Error response example

HTTP/1.1 404 Not Found
Content-Type application/json; charset=utf-8

In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description

HTTP codes

HTTP StatusDescription
400Request parameters are malformed
402The functionality/method is not available on the merchant plan
404Order, order item or item option is not found
500Request failed – there was an internal server error

Error response body (optional)

FieldTypeDescription
errorMessagestringError message
errorCodestringError code