Create order

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.

You can create only one order per API request. To create several orders, send several separate requests for each order.


When making a request with public access token, there are a few differences applied:

  • The paymentStatus can only be "AWAITING_PAYMENT" or "INCOMPLETE". Any other value is ignored.
  • privateAdminNotes field is always ignored.


AuthorizationstringoAuth token with mandatory Bearer before it. Example: Bearer e***s0, where e***s0 should be replaced with your oAuth token.


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


subtotalnumberOrder subtotal. Includes the sum of all products' cost in the order (item's price x quantity)
totalnumberOrder total cost. Includes shipping, taxes, discounts, etc.
emailstringCustomer email address
paymentMethodstringPayment method name
paymentModulestringPayment processor name
taxnumberTax total for order. Sum of all tax in order items, unless they were modified after order was placed
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, CUSTOM_PAYMENT_STATUS_1, CUSTOM_PAYMENT_STATUS_2, CUSTOM_PAYMENT_STATUS_3. Ignored when creating orders with public token
refererUrlstringURL of the page when order was placed (without hash (#) part)
orderCommentsstringCustomer's order comments, specified at checkout
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. 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
globalRefererstringURL that the customer came to the store from
createDatedateThe date/time of order placement, e.g 2023-06-22 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. It is present and visible in order details only if order status is not paid. When order becomes paid, paymentMessage is cleared
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
extraFields<ExtraFieldsInfo>Information about delivery date and time.
pickupTimestringOrder pickup time in the store date format, e.g.: "2017-10-17 05:00:00 +0000"
acceptMarketingbooleantrue 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
disableAllCustomerNotificationsbooleantrue 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
externalFulfillmentbooleanSet 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
externalOrderIdstringCorresponding order number in an external system where order is fulfilled. Use together with the externalFulfillment field
pricesIncludeTaxbooleantrue if the tax rate is included in order price. More details: Taxes in Ecwid
taxesOnShippingArray<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)
langstringOrder'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


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 or variation SKU. If you specified variation SKU, you must set selectedOptions field as well
shortDescriptionstringProduct description truncated to 120 characters
taxnumberTax amount applied to the item
combinationIdnumberThe ID of a chosen combination. If not specified, it will be calculated automatically
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
couponAppliedbooleantrue/false: shows whether a discount coupon is applied for this item
selectedOptionsArray<OrderItemOption>Product options values selected by the customer. Must be provided if you specify the sku field
taxesArray<OrderItemTax>Taxes applied to this order item
dimensions<ProductDimensions>Product dimensions info
isCustomerSetPricebooleantrue if price for the ordered product was set up by a customer ("Pay What You Want" feature is enabled). false otherwise.
isPreorderbooleantrue 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.


namestringTax name
valuenumberTax value in percent
totalnumberTax amount for the item
includeInPricebooleanDEPRECATED - refer to pricesIncludeTax field. true if the tax rate is included in product prices. More details: Taxes in Ecwid
taxClassCodestringTax classification code applied to product. See: Tax classes by country
taxClassNamestring(EN) Name of the tax classification code applied to product. See: Tax classes by country
taxOnShippingnumberTax on item shipping


namestringOption name
typestringOption 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)
valuestringSelected/entered value by customer. Multiple values separated by comma in a single string
selectionsArray<SelectionInfo>Details of selected product options. If sent in update order request, other fields will be regenerated based on information in this field


selectionTitlestringSelection title, as set by merchant
selectionModifiernumberSelection price modifier amount. Value is negative for negative modifiers
selectionModifierTypestringPrice modifier type: "PERCENT" or "ABSOLUTE"


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


namestringFull name
companyNamestringCompany name
streetstringAddress line 1 and address line 2, separated by '\n'
countryCodestringTwo-letter country code
postalCodestringPostal/ZIP code
stateOrProvinceCodestringState code, e.g. NY; full list of codes here:
phonestringPhone number


namestringCoupon title in store control panel
codestringCoupon code
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
applicationLimitstringApplication limit for discount coupons. Possible values: "UNLIMITED", "NEW_CUSTOMER_ONLY", "REPEAT_CUSTOMER_ONLY"
creationDatestringCoupon creation date
orderCountnumberNumber of uses
catalogLimit<DiscountCouponCatalogLimit>Products and categories the coupon can be applied to


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


shippingCarrierNamestringOptional. Is present for orders made with carriers, e.g. USPS or shipping applications.
shippingMethodNamestringShipping option name
estimatedTransitTimestringDelivery time estimation. Formats accepted: number "5", several days estimate "4-9"
pickupInstructionstringInstruction for customer on how to receive their products
fulfillmentTypestringContains one of the values: shipping, pickup, delivery


namestringHandling fee name set by store admin. E.g. Wrapping
valuenumberHandling fee value
descriptionstringHandling fee description for customer
taxes<HandlingFeeTaxes>Taxes applied to the handling fee


namestringTax name
valuenumberTax percent value
totalnumberTax total value


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


selectedPrice → value<SelectedPriceValue>Value of the price tier selected by a customer.


namestringTax name
valuenumberTax value in store settings, applied to destination zone
totalnumberTax total applied to shipping


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


ecwid_order_delivery_time_interval_enddateEnd of the delivery date interval.
ecwid_order_delivery_time_display_formatstringFormat of the delivery date chosen:DATE or DATETIME.
ecwid_order_delivery_time_interval_startdateStart of the delivery date interval.


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


id (deprecated)numberAn internal number of a created order in a store. It's deprecated. Use orderId instead. Learn more
orderidstringAn identifier of a created order in the store.

If the new number format of the order IDs is enabled in the store (order ID value looks like a combination of letters and numbers, for example, ‘XF1AD’ and it is randomly generated at the start of the checkout), then Ecwid will pass order ID value in the orderid field.
If the consecutive old number format of the order IDs is enabled in the store, then Ecwid will send a response with the internal order ID value in the id field.
Both order ID (orderid) and the internal order ID (id) can be used for API requests.


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 StatusDescription
400Request parameters are invalid
403Access token doesn't have create_orders scope
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)

errorMessagestringError message