Create order

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

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.

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
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`. Ignored when creating orders with public token
fulfillmentStatus	string	Fulfillment 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`. Ignored when creating orders with public token
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
createDate	date	The date/time of order placement, e.g `2023-06-22 18:57:19 +0000`
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. Ignored when creating orders with public token
extraFields	<ExtraFieldsInfo>	Information about delivery date and time.
pickupTime	string	Order pickup time in the store date format, e.g.: `"2017-10-17 05:00:00 +0000"`
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
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
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
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)

OrderItem

Field	Type	Description
name	string	Product name
quantity	number	Amount purchased
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 or variation SKU. If you specified variation SKU, you must set `selectedOptions` field as well
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. Must be provided if you specify the `sku` field
taxes	Array<OrderItemTax>	Taxes applied to this order item
dimensions	<ProductDimensions>	Product dimensions info
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	DEPRECATED - refer to `pricesIncludeTax` field. `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
taxOnShipping	number	Tax on item shipping

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"`

ProductDimensions

Field	Type	Description
length	number	Length of a product
width	number	Width of a product
height	number	Height of a product

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

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

IsCustomerSetPrice

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

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

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.

Response

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

CreateStatus

Field	Type	Description
id (deprecated)	number	An internal number of a created order in a store. It's deprecated. Use `orderId` instead. Learn more
orderid	string	An 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.

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 Status	Description
400	Request parameters are invalid
403	Access token doesn't have `create_orders` scope
404	The customer or any other linked object is not found in the store
500	Cannot create an order because of an error on the server

Error response body (optional)

Field	Type	Description
errorMessage	string	Error message