Skip to content

Create an order

POST
/stores/{storeRef}/orders
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/stores/example/orders \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-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 } ], "customer_id": 12 }'

Places an order for the store on behalf of a customer. Prices, the shipping fee, discounts and totals are always computed on the server, so any subtotal, shipping_fee, discount or total you send is ignored. Placing the order reserves stock for each line and can send the customer a confirmation email; it fails with 409 when stock is short or a carrier quote has changed. Each line needs a variant_id, and source defaults to admin.

Required scopes: write:orders

storeRef
required
string

The store’s ref, as returned by GET /stores.

Media typeapplication/json
object
cart_id

Cart ID (reference to cart used)

string

Example

uuid
customer_name
required

Customer name

string
>= 2 characters <= 255 characters

Example

Nguyen Van A
customer_email

Customer email. Omit for a walk-in customer who has none.

string

Example

customer@example.com
source

Where the order came from. Admin routes only.

string
Allowed values: pos phone admin
customer_phone

Customer phone number

string

Example

+84987654321
customer_avatar

Customer avatar URL

string

Example

https://example.com/avatar.jpg
payment_method
required

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

string

Example

cod
shipping_rate_id

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

number

Example

41
shipping_service_id

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

string
<= 32 characters

Example

svc_01HZX
shipping_quoted_amount

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

number

Example

32000
shipping_method_id

DEPRECATED: 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.

number

Example

1
subtotal

DEPRECATED: ignored. Always computed server-side from catalog prices.

number

Example

59980000
shipping_fee

DEPRECATED: ignored. Always computed server-side by the shipping rules engine.

number

Example

30000
discount

DEPRECATED: ignored. Always computed server-side from active promotions.

number

Example

0
total

DEPRECATED: ignored. Always computed server-side.

number

Example

60010000
shipping_street
required

Shipping street address

string

Example

123 Nguyen Hue Street
shipping_city
required

Shipping city code (province code, e.g., “79”, “01”, “11”)

string
/^\d{1,2}$/

Example

79
shipping_district

DEPRECATED - Shipping district code (use shipping_ward instead)

string

Example

760
shipping_ward

Shipping ward code (e.g., “27199”, “00001”)

string
/^\d{3,5}$/

Example

27199
shipping_postal_code

Shipping postal code

string

Example

700000
notes

Order notes

string

Example

Please call before delivery
promotion_id

Promotion ID for applied promotion code

number

Example

1
promotion_code

The discount code the shopper entered for promotion_id. Required on storefront checkout when that promotion is a discount code.

string
<= 100 characters

Example

SUMMER10
customer_address_id

Customer address ID (for saved addresses)

number

Example

1
items
required

Order items

Array<object>
object
product_id
required

Product ID

number

Example

1
product_name

DEPRECATED: ignored. Snapshotted from the catalog server-side.

string

Example

iPhone 15 Pro
product_image

DEPRECATED: ignored. Snapshotted from the catalog server-side.

string

Example

https://example.com/image.jpg
variant_id
required

Product variant ID. Required: every order line is a variant.

number
>= 1

Example

1
variant_name

DEPRECATED: ignored. The variant label is snapshotted from the catalog server-side.

string

Example

128GB Blue
quantity
required

Quantity ordered

number
>= 1

Example

2
variant_options

DEPRECATED: ignored. The line’s option/value pairs are snapshotted from the catalog variant server-side.

Array<object>
object
optionName

Option/attribute label shown to the shopper

string

Example

Màu sắc
optionValue

Chosen value label shown to the shopper

string

Example

Xanh navy
price

DEPRECATED: ignored. The unit price is resolved from the catalog server-side; any value sent here is discarded.

number

Example

29990000
original_price

DEPRECATED: ignored. Resolved from the catalog server-side.

number

Example

32990000
total

DEPRECATED: ignored. Computed server-side as price x quantity.

number

Example

59980000
customer_id

Customer to link the order to (customers.id). Must be a customer of this store; the request is refused with ORDER_CUSTOMER_NOT_FOUND otherwise. Omit to place the order without a linked customer.

number
>= 1

Example

12
Media typeapplication/json
object
order_status
required

Lifecycle status of the order.

string
Allowed values: pending confirmed processing cancelled on_hold completed
previous_order_status

The status the order was in before it was put on hold, or null. Resuming restores it.

string
nullable
Allowed values: pending confirmed processing cancelled on_hold completed
fulfillment_status
required

Warehouse status: whether the items have been picked and packed, or returned.

string
Allowed values: unfulfilled fulfilled returned return_requested
shipping_status
required

Delivery status.

string
Allowed values: not_shipped shipped in_transit out_for_delivery delivered delivery_failed
payment_status
required

Payment status.

string
Allowed values: pending authorized paid captured failed refunded voided
id

Order ID.

number
user_id

ID of the signed-in user who placed the order, or null for a guest or a staff-keyed order.

string
nullable
cart_id

ID of the cart the order was created from, or null.

string
nullable
customer_id

ID of the customer the order is linked to, or null for a guest checkout.

number
nullable
order_number
required

Sequence number of the order, unique within the store.

number
order_code
required

Customer-facing order code, such as #1001. Prefer it for display.

string
customer_name
required

Customer name.

string
customer_email
required

Customer email, or null for a walk-in customer without one.

string
nullable
customer_phone

Customer phone number, or null.

string
nullable
customer_avatar

Customer avatar URL, or null.

string
nullable
source
required

How the order was captured: online, pos, phone or admin.

string
store_sales_channel_id

ID of the sales channel the order is attributed to, or null.

number
nullable
created_by_user_id

ID of the staff member who keyed the order in, or null.

string
nullable
created_by

The staff member behind created_by_user_id. Present only when a single order is fetched.

object
id
required

Staff user ID.

string
name
required

Display name, or null when the member has not set one.

string
nullable
email
required

Email address, or null.

string
nullable
status

Deprecated combined status. Use order_status, fulfillment_status, shipping_status and payment_status instead.

string
nullable
payment_method

Code of the payment method, as configured on the store, such as cod.

string
nullable
subtotal
required

Sum of the line totals, in the order’s currency.

number
shipping_fee
required

Shipping fee charged.

number
tax
required

Tax amount.

number
discount
required

Total discount applied to the order.

number
total
required

Amount due: subtotal plus shipping and tax, minus discounts.

number
currency_code

ISO 4217 currency code the amounts are in, such as VND.

string
original_subtotal

Subtotal before promotions, or null when it was not recorded.

number
nullable
original_shipping_fee

Shipping fee before promotions, or null when it was not recorded.

number
nullable
shipping_discount

Part of the discount that came off shipping, or null.

number
nullable
shipping_street
required

Street address to deliver to.

string
shipping_city
required

Province code of the delivery address.

string
shipping_city_name

Province name. Present only when a single order is fetched.

string
nullable
shipping_district

Deprecated district code. New orders use shipping_ward.

string
nullable
shipping_ward

Ward code of the delivery address, or null.

string
nullable
shipping_ward_name

Ward name. Present only when a single order is fetched.

string
nullable
shipping_postal_code

Postal code, or null.

string
nullable
tracking_number

Tracking number of the shipment, or null.

string
nullable
shipping_carrier

Name of the carrier, or null.

string
nullable
shipping_method_id

Deprecated: always null on new orders.

number
nullable
shipping_method_name

Name of the shipping method. Present only when include_order_shipping is true.

string
nullable
shipping_rate_id

ID of the shipping rate used. Present only when include_order_shipping is true.

number
nullable
notes

Free-text notes on the order, or null.

string
nullable
created_at

When the order was placed, as an ISO 8601 timestamp.

string
updated_at

When the order was last changed, as an ISO 8601 timestamp.

string
items
required

The order’s lines. Empty unless items are requested (the list omits them by default).

Array<object>
object
id

Order item ID.

number
order_id

ID of the order the line belongs to.

number
product_id

ID of the product, or null when the product has since been removed.

number
nullable
product_name
required

Product name as it was when the order was placed.

string
product_image

Product image URL as it was when the order was placed, or null.

string
nullable
variant_id

ID of the purchased variant, or null when the variant has since been removed.

number
nullable
variant_name

Variant label as it was when the order was placed, or null.

string
nullable
quantity
required

Units ordered.

number
original_price

Unit price before any promotion, or null when it was not recorded.

number
nullable
price
required

Unit price charged, after promotions.

number
total
required

Line total: the unit price times the quantity.

number
discount

Total discount applied to the whole line, or null when none.

number
nullable

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.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The key is missing, invalid, revoked or expired.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

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.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The resource does not exist in this store.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The request conflicts with the resource’s current state.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}

The request is valid but cannot be processed.

Media typeapplication/json
One of:
object
statusCode
required

The HTTP status code.

number
message
required

What went wrong; validation failures list one message per problem.

One of:
string
error

The HTTP status text, such as Bad Request.

string

Example generated

{
"statusCode": 1,
"message": [
"example"
],
"error": "example"
}