put https://app.ecwid.com/api/v3//orders/
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.
Access scopes
Requires the following access scope: update_orders
Request body
A JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
| subtotal | number | Order subtotal. Includes the sum of all products' cost in the order (item's price x quantity) |
| total | number | Order total cost. Includes shipping, taxes, discounts, etc. |
| giftCardRedemption | number | Amount deducted from the Gift Card balance and applied to order total. |
| totalBeforeGiftCardRedemption | number | Order total before the Gift Card was applied. |
| string | Customer email address | |
| paymentMethod | string | Payment method name |
| paymentModule | string | Payment processor name |
| tax | number | Tax total for order. Sum of all tax in order items, unless they were modified after order was placed |
| customerTaxExempt | boolean | true if customer is tax exempt, false otherwise. Learn more |
| customerTaxId | string | Customer tax ID |
| customerTaxIdValid | boolean | true if customer tax ID is valid, false otherwise |
| reversedTaxApplied | boolean | true if order tax was set to 0 because customer specified their valid tax ID in checkout process. false otherwise |
| b2b_b2c | string | Order type: business-to-business (b2b) or business-to-consumer (b2c) |
| customerRequestedInvoice | boolean | true if customer requested an invoice, false otherwise |
| customerFiscalCode | string | Fiscale code of a customer |
| electronicInvoicePecEmail | string | PEC email for invoices |
| electronicInvoiceSdiCode | string | SDI code for invoices |
| ipAddress | string | Customer IP |
| couponDiscount | number | Discount applied to order using a coupon |
| paymentStatus | string | Payment status. Supported values: AWAITING_PAYMENT, PAID, CANCELLED, REFUNDED, PARTIALLY_REFUNDED, INCOMPLETE, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3. |
| fulfillmentStatus | string | Fulfilment status. Supported values: AWAITING_PROCESSING, PROCESSING, SHIPPED, DELIVERED, WILL_NOT_DELIVER, RETURNED, READY_FOR_PICKUP, OUT_FOR_DELIVERY, CUSTOM_FULFILLMENT_STATUS_1, CUSTOM_FULFILLMENT_STATUS_2, CUSTOM_FULFILLMENT_STATUS_3. |
| refererUrl | string | URL of the page when order was placed (without hash (#) part) |
| orderComments | string | Customer's order comments, specified at checkout |
| volumeDiscount | number | Sum of discounts based on subtotal. Is included into the discount field |
| customerId | number | Unique customer internal ID (if the order is placed by a registered user) |
| hidden | boolean | Determines if the order is hidden (removed from the list). Applies to unfinished orders only. |
| membershipBasedDiscount | number | Sum of discounts based on customer group. Is included into the discount field |
| totalAndMembershipBasedDiscount | number | The sum of discount based on subtotal AND customer group. Is included into the discount field |
| discount | number | The sum of all applied discounts except for the coupon discount. To get the total order discount, take the sum of couponDiscount and discount field values. Total order discount is a sum of all discounts applied to items (both regular discount and discount coupons) unless they were modified after order was placed |
| globalReferer | string | URL that the customer came to the store from |
| customerGroup | string | The name of group (membership) the customer belongs to |
| discountCoupon | <DiscountCouponInfo> | Information about applied coupon |
| items | Array<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 |
| additionalInfo | Map<string,string> | Additional order information if any (reserved for future use) |
| paymentParams | Map<string,string> | Additional payment parameters entered by customer on checkout, e.g. PO number in "Purchase order" payments |
| discountInfo | Array<DiscountInfo> | Information about applied discounts (coupons are not included) |
| trackingNumber | string | Shipping tracking code |
| paymentMessage | string | Message from the payment processor if any. It is present and visible in order details only if order status is not paid. When order becomes paid, paymentMessage is cleared |
| externalTransactionId | string | Transaction ID / invoice number of the order in the payment system (e.g. PayPal transaction ID) |
| affiliateId | string | Affiliate ID |
| creditCardStatus | <CreditCardStatus> | The status of credit card payment |
| privateAdminNotes | string | Private note about the order from store owner |
| extraFields | <ExtraFieldsInfo> | Information about order extra fields, both internal and custom fields added from Control Panel or by applications |
| pickupTime | string | Order pickup time in the store date format, e.g.: "2017-10-17 05:00:00 +0000" |
| taxesOnShipping | Array<TaxOnShipping> | Taxes applied to shipping. null for old orders, [] for orders with taxes applied to subtotal only. Are not recalculated if order is updated later manually. Is calculated like: (shippingRate + handlingFee)*(taxValue/100) |
| acceptMarketing | boolean | true if customer has accepted email marketing and you can use their email for promotions. If value is false, you can't use this email for promotions |
| refererId | string | Referer identifier. Can be set in storefront via JS or by creating / updating an order with REST API |
| disableAllCustomerNotifications | boolean | true if no email notifications are sent to customer. If false or empty, then email notifications are sent to customer according to store mail notification settings. This field does not influence admin email notifications |
| externalFulfillment | boolean | Set true if order is fulfilled in an external system; Ecwid will hide fulfillment status change feature and ability to set tracking number within Ecwid Control Panel in order details. Set false to manage order fulfillment within Ecwid Control Panel |
| utmData | Array<utmData> | UTM parameters tracked for the order. See more details in Help Center |
| externalOrderId | string | Corresponding order number in an external system where order is fulfilled. Use together with the externalFulfillment field |
| pricesIncludeTax | boolean | true if the tax rate is included in order price. More details: Taxes in Ecwid |
| orderExtraFields | array<OrderExtraFieldsInfo> | Extra fields information in the order |
| lang | string | Order's language (optional). If this field has a value matching one of the active store translations, all customer emails for the order will use this language. Get a list of active store languages here |
OrderItem
| Field | Type | Description |
|---|---|---|
| id | number | Order item ID. |
| quantity | number | Amount purchased |
| name | string | Product name |
| productId | number | Store product ID |
| categoryId | number | ID 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 |
| price | number | Price of ordered item in the cart |
| productPrice | number | Basic product price without options markups, wholesale discounts etc. |
| weight | number | Product weight |
| sku | string | Product/variation SKU |
| shortDescription | string | Product description truncated to 120 characters |
| tax | number | Tax amount applied to the item |
| combinationId | number | The ID of a chosen combination. If not specified, it will be calculated automatically |
| shipping | number | Order item shipping cost |
| quantityInStock | number | The number of products in stock in the store |
| isShippingRequired | boolean | true/false: shows whether the item requires shipping |
| trackQuantity | boolean | true/false: shows whether the store admin set to track the quantity of this product and get low stock notifications |
| fixedShippingRateOnly | boolean | true/false: shows whether the fixed shipping rate is set for the product |
| fixedShippingRate | number | Fixed shipping rate for the product |
| digital | boolean | true/false: shows whether the item has downloadable files attached |
| couponApplied | boolean | true/false: shows whether a discount coupon is applied for this item |
| selectedOptions | Array<OrderItemOption> | Product options values selected by the customer |
| taxes | Array<OrderItemTax> | Taxes applied to this order item |
| isCustomerSetPrice | boolean | true if price for the ordered product was set up by a customer ("Pay What You Want" feature is enabled). false otherwise. |
| isPreorder | boolean | true if the product is pre-ordered because it was out of stock. Learn more about Accepting pre-orders. Otherwise the field should not be passed. |
OrderItemTax
| Field | Type | Description |
|---|---|---|
| name | string | Tax name |
| value | number | Tax value in percent |
| total | number | Tax amount for the item |
| includeInPrice | boolean | true if the tax rate is included in product prices. More details: Taxes in Ecwid |
| taxClassCode | string | Tax classification code applied to product. See: Tax classes by country |
| taxClassName | string | (EN) Name of the tax classification code applied to product. See: Tax classes by country |
OrderItemOption
| Field | Type | Description |
|---|---|---|
| name | string | Option name |
| type | string | Option type. One of:
|
| value | string | Selected/entered value by customer. Multiple values separated by comma in a single string |
| selections | Array<SelectionInfo> | Details of selected product options. If sent in update order request, other fields will be regenerated based on information in this field |
SelectionInfo
| Field | Type | Description |
|---|---|---|
| selectionTitle | string | Selection title, as set by merchant |
| selectionModifier | number | Selection price modifier amount. Value is negative for negative modifiers |
| selectionModifierType | string | Price modifier type: "PERCENT" or "ABSOLUTE" |
PersonInfo
| Field | Type | Description |
|---|---|---|
| name | string | Full name |
| companyName | string | Company name |
| street | string | Address line 1 and address line 2, separated by '\n' |
| city | string | City |
| countryCode | string | Two-letter country code |
| postalCode | string | Postal/ZIP code |
| stateOrProvinceCode | string | State code, e.g. NY; full list of codes here: https://api-docs.ecwid.com/reference/list-of-state-codes |
| phone | string | Phone number |
OrderItemDiscounts
| Field | Type | Description |
|---|---|---|
| discountInfo | <OrderItemDiscountInfo> | Info about discounts applied to item |
| total | number | Total order item discount value for this discount |
OrderItemDiscountInfo
| Field | Type | Description |
|---|---|---|
| value | number | Discount value |
| type | string | Discount type: ABS or PERCENT |
| base | string | Discount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP, CUSTOM |
| orderTotal | number | Minimum order subtotal the discount applies to |
DiscountCouponInfo
| Field | Type | Description |
|---|---|---|
| name | string | Coupon title in store control panel |
| code | string | Coupon code |
| discountType | string | Discount type: ABS, PERCENT, SHIPPING, ABS_AND_SHIPPING, PERCENT_AND_SHIPPING |
| status | string | Discount coupon state: ACTIVE, PAUSED, EXPIRED or USEDUP |
| discount | number | Discount amount |
| launchDate | string | The date of coupon launch, e.g. 2014-06-06 08:00:00 +0000 |
| expirationDate | string | Coupon expiration date, e.g. 2014-06-06 08:00:00 +0000 |
| totalLimit | number | The minimum order subtotal the coupon applies to |
| usesLimit | string | Number of uses limitation: UNLIMITED, ONCEPERCUSTOMER, SINGLE |
| applicationLimit | string | Application limit for discount coupons. Possible values: "UNLIMITED", "NEW_CUSTOMER_ONLY", "REPEAT_CUSTOMER_ONLY" |
| creationDate | string | Coupon creation date |
| orderCount | number | Number of uses |
| catalogLimit | <DiscountCouponCatalogLimit> | Products and categories the coupon can be applied to |
DiscountCouponCatalogLimit
| Field | Type | Description |
|---|---|---|
| products | Array<number> | The list of product IDs the coupon can be applied to |
| categories | Array<number> | The list of category IDs the coupon can be applied to |
ShippingOptionInfo
| Field | Type | Description |
|---|---|---|
| shippingCarrierName | string | Optional. Is present for orders made with carriers, e.g. USPS or shipping applications. |
| shippingMethodName | string | Shipping option name |
| shippingRate | number | Rate |
| estimatedTransitTime | string | Delivery time estimation. Formats accepted: number "5", several days estimate "4-9" |
| pickupInstruction | string | Instruction for customer on how to receive their products |
| fulfillmentType | string | Contains one of the values: shipping, pickup, delivery |
HandlingFeeInfo
| Field | Type | Description |
|---|---|---|
| name | string | Handling fee name set by store admin. E.g. Wrapping |
| value | number | Handling fee value |
| description | string | Handling fee description for customer |
| taxes | <HandlingFeeTaxes> | Taxes applied to the handling fee |
HandlingFeeTaxes
| Field | Type | Description |
|---|---|---|
| name | string | Tax name |
| value | number | Tax percent value |
| total | number | Tax total value |
DiscountInfo
| Field | Type | Description |
|---|---|---|
| value | number | Discount value |
| type | string | Discount type: ABS or PERCENT |
| base | string | Discount base, one of ON_TOTAL, ON_MEMBERSHIP, ON_TOTAL_AND_MEMBERSHIP |
| orderTotal | number | Minimum order subtotal the discount applies to |
CreditCardStatus
| Field | Type | Description |
|---|---|---|
| avsMessage | string | Address verification status returned by the payment system |
| cvvMessage | string | Credit card verification status returned by the payment system |
ExtraFieldsInfo
| Field | Type | Description |
|---|---|---|
| ecwid_order_delivery_time_interval_end | date | End of the delivery date interval. |
| ecwid_order_delivery_time_display_format | string | Format of the delivery date chosen:DATE or DATETIME. |
| ecwid_order_delivery_time_interval_start | date | Start of the delivery date interval. |
TaxOnShipping
| Field | Type | Description |
|---|---|---|
| name | string | Tax name |
| value | number | Tax value in store settings, applied to destination zone |
| total | number | Tax total applied to shipping |
IsCustomerSetPrice
| Field | Type | Description |
|---|---|---|
| selectedPrice → value | <SelectedPriceValue> | Value of the price tier selected by a customer. |
OrderExtraFieldsInfo
| Field | Type | Description |
|---|---|---|
| id | string | Your custom name saved for the order extra field |
| value | string | Extra field value. Length cannot exceed 255 characters |
| customerInputType | string | One of: "","TEXT", "SELECT", "DATETIME" |
| title | string | Extra field title. Displayed for a customer at checkout if the field is visible |
| orderDetailsDisplaySection | string | One of: shipping_info , billing_info, customer_info, order_comments. Empty string for hidden fields. |
| orderBy | string | Extra field position. Use it to sort fields within the same orderDetailsDisplaySection |
utmData
| Field | Type | Description |
|---|---|---|
| source | string | Traffic source - indicated where customers come from |
| campaign | string | Indicates a specific advertising campaign |
| medium | string | Type of traffic - indicates the method for bringing customers |
Response
A JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
| updateCount | number | The number of updated orders (1 or 0 depending on whether the update was successful) |
Errors
In case of error, Ecwid responds with an error HTTP status code and, optionally, JSON-formatted body containing error description
HTTP codes
| HTTP Status | Description |
|---|---|
| 400 | Request parameters are invalid |
| 403 | Access token doesn't have update_orders scope |
| 404 | The order is not found |
| 415 | Unsupported content-type: expected application/json or text/json |
| 500 | Cannot update the order info because of an error on the server |
Error response body (optional)
| Field | Type | Description |
|---|---|---|
| errorMessage | string | Error message |