Update order

put https://app.ecwid.com/api/v3/{storeId}/orders/{orderId}

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 required: read_orders and update_orders

Headers

Name	Type	Description
Authorization	string	oAuth token with mandatory `Bearer` before it. Example: `Bearer e*s0`, where `e*s0` should be replaced with your oAuth token.

Request

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

Order

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.
email	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

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: `CHOICE` (dropdown, radio button or size) `CHOICES` (checkboxes) `TEXT` (text input and text area) `DATE` (date/time) `FILES` (Sets option type only. Impossible to upload the file on behalf of customers via REST API)
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 of type 'UpdateStatus' with the following fields:

UpdateStatus

Field	Type	Description
updateCount	number	The 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 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