Place an order as the signed-in shopper
const url = 'https://apibase.ecomweb.app/api/v1/tenant/stores/example/customers/orders';const options = { method: 'POST', headers: { 'x-storefront-api-key': '<x-storefront-api-key>', Authorization: 'Bearer <token>', 'Content-Type': 'application/json' }, body: '{"cart_id":"uuid","customer_name":"Nguyen Van A","customer_email":"customer@example.com","source":"pos","customer_phone":"+84987654321","customer_avatar":"https://example.com/avatar.jpg","payment_method":"cod","shipping_rate_id":41,"shipping_service_id":"svc_01HZX","shipping_quoted_amount":32000,"shipping_method_id":1,"subtotal":59980000,"shipping_fee":30000,"discount":0,"total":60010000,"shipping_street":"123 Nguyen Hue Street","shipping_city":"79","shipping_district":"760","shipping_ward":"27199","shipping_postal_code":"700000","notes":"Please call before delivery","promotion_id":1,"promotion_code":"SUMMER10","customer_address_id":1,"items":[{"product_id":1,"product_name":"iPhone 15 Pro","product_image":"https://example.com/image.jpg","variant_id":1,"variant_name":"128GB Blue","quantity":2,"variant_options":[{"optionName":"Màu sắc","optionValue":"Xanh navy"}],"price":29990000,"original_price":32990000,"total":59980000}]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://apibase.ecomweb.app/api/v1/tenant/stores/example/customers/orders \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'x-storefront-api-key: <x-storefront-api-key>' \ --data '{ "cart_id": "uuid", "customer_name": "Nguyen Van A", "customer_email": "customer@example.com", "source": "pos", "customer_phone": "+84987654321", "customer_avatar": "https://example.com/avatar.jpg", "payment_method": "cod", "shipping_rate_id": 41, "shipping_service_id": "svc_01HZX", "shipping_quoted_amount": 32000, "shipping_method_id": 1, "subtotal": 59980000, "shipping_fee": 30000, "discount": 0, "total": 60010000, "shipping_street": "123 Nguyen Hue Street", "shipping_city": "79", "shipping_district": "760", "shipping_ward": "27199", "shipping_postal_code": "700000", "notes": "Please call before delivery", "promotion_id": 1, "promotion_code": "SUMMER10", "customer_address_id": 1, "items": [ { "product_id": 1, "product_name": "iPhone 15 Pro", "product_image": "https://example.com/image.jpg", "variant_id": 1, "variant_name": "128GB Blue", "quantity": 2, "variant_options": [ { "optionName": "Màu sắc", "optionValue": "Xanh navy" } ], "price": 29990000, "original_price": 32990000, "total": 59980000 } ] }'Places an order from the shopper’s cart or item list. Prices, the shipping fee, discounts and totals are always computed on the server, so any subtotal, shipping_fee, discount, total or line price you send is ignored, as are source and the line display fields. Each line needs a variant_id. Placing the order reserves stock and can send a confirmation email; it fails with 409 when stock is short or a carrier quote has changed. Read the payment methods first to choose payment_method, then start a gateway payment with the order code when the method needs one. The order is linked to the shopper’s customer record. A visitor who is not signed in uses the guest order route.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Cart ID (reference to cart used)
Example
uuidCustomer name
Example
Nguyen Van ACustomer email. Omit for a walk-in customer who has none.
Example
customer@example.comWhere the order came from. Admin routes only.
Customer phone number
Example
+84987654321Customer avatar URL
Example
https://example.com/avatar.jpgPayment method code, as configured on the store’s enabled payment methods. Not a fixed list: the store owns this vocabulary, and a code the store has not enabled is rejected.
Example
codShipping rate chosen by the shopper (shipping_rates.id). The fee for it is always computed server-side; only the choice of rate comes from the client. Omit to let the server pick the store’s default (cheapest) option for the address. A rate that does not match one of the options priced for this address is rejected rather than silently re-priced.
Example
41The chosen carrier option’s carrier_service_id. Required with shipping_rate_id when that rate is carrier-calculated (AllinGo); a carrier rate sent without it is rejected with ORDER_SHIPPING_RATE_UNAVAILABLE.
Example
svc_01HZXThe chosen option’s amount as the buyer saw it (integer VND). For a carrier option whose cached quote has expired, placement requotes live and rejects with SHIPPING_QUOTE_CHANGED (409, details.options) when this is absent or differs from the new amount. Ignored for a fixed rate.
Example
32000DEPRECATED: accepted but ignored. Shipping methods no longer exist; use shipping_rate_id to choose a rate. Kept for one release so an older client does not 400.
Example
1DEPRECATED: ignored. Always computed server-side from catalog prices.
Example
59980000DEPRECATED: ignored. Always computed server-side by the shipping rules engine.
Example
30000DEPRECATED: ignored. Always computed server-side from active promotions.
Example
0DEPRECATED: ignored. Always computed server-side.
Example
60010000Shipping street address
Example
123 Nguyen Hue StreetShipping city code (province code, e.g., “79”, “01”, “11”)
Example
79DEPRECATED - Shipping district code (use shipping_ward instead)
Example
760Shipping ward code (e.g., “27199”, “00001”)
Example
27199Shipping postal code
Example
700000Order notes
Example
Please call before deliveryPromotion ID for applied promotion code
Example
1The discount code the shopper entered for promotion_id. Required on storefront checkout when that promotion is a discount code.
Example
SUMMER10Customer address ID (for saved addresses)
Example
1Order items
object
Product ID
Example
1DEPRECATED: ignored. Snapshotted from the catalog server-side.
Example
iPhone 15 ProDEPRECATED: ignored. Snapshotted from the catalog server-side.
Example
https://example.com/image.jpgProduct variant ID. Required: every order line is a variant.
Example
1DEPRECATED: ignored. The variant label is snapshotted from the catalog server-side.
Example
128GB BlueQuantity ordered
Example
2DEPRECATED: ignored. The line’s option/value pairs are snapshotted from the catalog variant server-side.
object
Option/attribute label shown to the shopper
Example
Màu sắcChosen value label shown to the shopper
Example
Xanh navyDEPRECATED: ignored. The unit price is resolved from the catalog server-side; any value sent here is discarded.
Example
29990000DEPRECATED: ignored. Resolved from the catalog server-side.
Example
32990000DEPRECATED: ignored. Computed server-side as price x quantity.
Example
59980000Responses
Section titled “Responses”object
Lifecycle status of the order.
The status the order was in before it was put on hold, or null. Resuming restores it.
Warehouse status: whether the items have been picked and packed, or returned.
Delivery status.
Payment status.
Order ID.
ID of the signed-in user who placed the order, or null for a guest or a staff-keyed order.
ID of the cart the order was created from, or null.
ID of the customer the order is linked to, or null for a guest checkout.
Sequence number of the order, unique within the store.
Customer-facing order code, such as #1001. Prefer it for display.
Customer name.
Customer email, or null for a walk-in customer without one.
Customer phone number, or null.
Customer avatar URL, or null.
ID of the sales channel the order is attributed to, or null.
Deprecated combined status. Use order_status, fulfillment_status, shipping_status and payment_status instead.
Code of the payment method, as configured on the store, such as cod.
Sum of the line totals, in the order’s currency.
Shipping fee charged.
Tax amount.
Total discount applied to the order.
Amount due: subtotal plus shipping and tax, minus discounts.
ISO 4217 currency code the amounts are in, such as VND.
Subtotal before promotions, or null when it was not recorded.
Shipping fee before promotions, or null when it was not recorded.
Part of the discount that came off shipping, or null.
Street address to deliver to.
Province code of the delivery address.
Province name. Present only when a single order is fetched.
Deprecated district code. New orders use shipping_ward.
Ward code of the delivery address, or null.
Ward name. Present only when a single order is fetched.
Postal code, or null.
Tracking number of the shipment, or null.
Name of the carrier, or null.
Deprecated: always null on new orders.
Name of the shipping method. Present only when include_order_shipping is true.
ID of the shipping rate used. Present only when include_order_shipping is true.
Free-text notes on the order, or null.
When the order was placed, as an ISO 8601 timestamp.
When the order was last changed, as an ISO 8601 timestamp.
The order’s lines. Empty unless items are requested (the list omits them by default).
object
Order item ID.
ID of the order the line belongs to.
ID of the product, or null when the product has since been removed.
Product name as it was when the order was placed.
Product image URL as it was when the order was placed, or null.
ID of the purchased variant, or null when the variant has since been removed.
Variant label as it was when the order was placed, or null.
Units ordered.
Unit price before any promotion, or null when it was not recorded.
Unit price charged, after promotions.
Line total: the unit price times the quantity.
Total discount applied to the whole line, or null when none.
Example
{ "order_status": "pending", "previous_order_status": "pending", "fulfillment_status": "unfulfilled", "shipping_status": "not_shipped", "payment_status": "pending"}The request is malformed or failed validation.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key is missing, invalid, revoked or expired.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The key may not do this: a missing scope, a readonly key, a publishable key on a Store API route, or a disallowed origin.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The resource does not exist in this store.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request conflicts with the resource’s current state.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}The request is valid but cannot be processed.
object
The HTTP status code.
What went wrong; validation failures list one message per problem.
The HTTP status text, such as Bad Request.
object
A stable, machine-readable error code.
A human-readable explanation.
Extra context about the error, when there is any.
object
When the error happened, as an ISO 8601 timestamp.
Example generated
{ "statusCode": 1, "message": [ "example" ], "error": "example"}