Update an order
const url = 'https://apibase.ecomweb.app/api/v1/stores/example/orders/1';const options = { method: 'PUT', headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'}, body: '{"order_status":"pending","fulfillment_status":"unfulfilled","shipping_status":"not_shipped","payment_status":"pending","status":"pending","tracking_number":"VN123456789","notes":"Updated delivery instructions","shipping_fee":35000,"reason":"Customer asked to cancel by phone","restock":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request PUT \ --url https://apibase.ecomweb.app/api/v1/stores/example/orders/1 \ --header 'Content-Type: application/json' \ --header 'x-api-key: <x-api-key>' \ --data '{ "order_status": "pending", "fulfillment_status": "unfulfilled", "shipping_status": "not_shipped", "payment_status": "pending", "status": "pending", "tracking_number": "VN123456789", "notes": "Updated delivery instructions", "shipping_fee": 35000, "reason": "Customer asked to cancel by phone", "restock": true }'Updates the fields you send. Status changes are checked against the order state machine, and a change it does not allow is refused with 400 ORDER_TRANSITION_NOT_ALLOWED; call the allowed-transitions route to see what the order accepts now.
Allowed transitions:
- Order status: pending to confirmed, cancelled or on_hold; confirmed to processing, cancelled or on_hold; processing to completed, cancelled or on_hold; on_hold back to the status it was held from (pending if none) or to cancelled; cancelled and completed are final.
- Fulfillment: unfulfilled to fulfilled; fulfilled to return_requested; return_requested to returned or back to fulfilled.
- Shipping: not_shipped to shipped; shipped to in_transit, delivery_failed or delivered; in_transit to out_for_delivery, delivery_failed or delivered; out_for_delivery to delivered, delivery_failed or in_transit; delivery_failed to in_transit, out_for_delivery or not_shipped; delivered is final.
- Payment: pending to authorized, paid, failed or voided; authorized to captured, paid, voided or failed; captured to paid or refunded; paid to refunded; failed to pending.
Guards:
- Confirming or processing needs a payment that is valid for the payment method.
- Fulfilling needs the order confirmed or processing, with a valid payment.
- Completing needs the shipment delivered and the payment status paid, captured or refunded.
- Cancelling is refused with 400 once the shipment is shipped, in_transit, out_for_delivery or delivered, and a payment that was collected (captured or paid) must be refundable. Stock is put back unless
restockis false. - While an order is on hold, only resuming or cancelling it is accepted.
An unknown order ID returns 400.
Required scopes: write:orders
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The order ID.
The store’s ref, as returned by GET /stores.
Request Bodyrequired
Section titled “Request Bodyrequired”object
Order status (lifecycle state)
Example
confirmedFulfillment status (warehouse/picking state)
Example
fulfilledShipping status (delivery state)
Example
shippedPayment status
Example
paidLegacy order status (DEPRECATED - use order_status, fulfillment_status, shipping_status instead)
Example
confirmedTracking number for shipment
Example
VN123456789Order notes
Example
Updated delivery instructionsUpdated shipping fee
Example
35000Optional reason recorded on the order timeline for any status change in this request. It is recorded only when the same request changes a tracked field (a status or the tracking number); a request carrying only a reason records nothing.
Example
Customer asked to cancel by phoneWhen this update cancels the order or completes a return, put its stock back. Defaults to true. Ignored for other updates.
Example
trueResponses
Section titled “Responses”The updated order.
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.
How the order was captured: online, pos, phone or admin.
ID of the sales channel the order is attributed to, or null.
ID of the staff member who keyed the order in, or null.
The staff member behind created_by_user_id. Present only when a single order is fetched.
object
Staff user ID.
Display name, or null when the member has not set one.
Email address, 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 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"}