Skip to content

Place an order

POST
/public/stores/{storeRef}/orders
curl --request POST \
--url https://apibase.ecomweb.app/api/v1/public/stores/example/orders \
--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. Orders placed here are always guest orders with no customer record, even when the shopper is signed in: a signed-in shopper should use the signed-in order route so the order is linked to their account. Keep the returned order_code: the guest can look the order up with it, and it identifies the order when starting a payment.

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
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
store_sales_channel_id

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

number
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"
}