Skip to content

Look up an order as a guest

GET
/public/stores/{storeRef}/orders/lookup
curl --request GET \
--url 'https://apibase.ecomweb.app/api/v1/public/stores/example/orders/lookup?order_code=DH-1042-26&order_number=12345&customer_email=customer%40example.com&customer_phone=%2B84987654321' \
--header 'x-storefront-api-key: <x-storefront-api-key>'

Finds one order so a guest can track it. Send the order code shown at checkout (order_code, or the older numeric order_number). customer_email or customer_phone, when sent, must match the order; they are optional and are not currently required, so the order code alone returns the order. The response carries the order’s lines, shipment tracking and whether it can still be cancelled. When nothing matches, the status is still 200 and the body is { "message": "Order not found" }, so check for message rather than the status.

storeRef
required
string

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

order_code
string

Example

DH-1042-26

The order code shown to the customer, e.g. DH-1042-26. A bare sequence is also accepted. Preferred over order_number.

order_number
number

Example

12345

Numeric order sequence. Retained for clients predating order codes; prefer order_code.

customer_email
string

Example

customer@example.com

Customer email address

customer_phone
string

Example

+84987654321

Customer phone number (alternative to email)

The matching order, or { "message": "Order not found" } when none matches.

Media typeapplication/json
One of:
object
items
required

The order’s lines.

Array<object>
object
id
required

Order item ID.

number
product_name
required

Product name as it was when the order was placed.

string
variant_name
required

Variant label, or null.

string
nullable
product_image
required

Product image URL, or null.

string
nullable
quantity
required

Units ordered.

number
price
required

Unit price charged, after promotions.

number
original_price
required

Unit price before promotions, or null.

number
nullable
discount
required

Discount applied to the line, or null.

number
nullable
total
required

Line total.

number
shipment
required

The order’s shipment, or null when none has been booked or tracking could not be read.

object
status
required

Normalized shipment status, or null.

string
nullable
Allowed values: booked picked_up in_transit out_for_delivery delivered failed returned cancelled
events
required

Tracking steps from the carrier.

Array<object>
object
occurred_at
required

When the step happened, as an ISO 8601 timestamp.

string
label
required

What happened, in the carrier’s wording.

string
location
required

Where it happened, or null.

string
nullable
carrier_name
required

Carrier name, or null.

string
nullable
carrier_logo_url
required

URL of the carrier’s logo, or null.

string
nullable
service_name
required

Name of the carrier service, or null.

string
nullable
tracking_number
required

Tracking number, or null.

string
nullable
track_link
required

Link to the carrier’s tracking page, or null.

string
nullable
id
required

Order ID.

number
order_number
required

Sequence number of the order, unique within the store.

number
order_code
required

Customer-facing order code.

string
customer_name
required

Customer name.

string
customer_email
required

Customer email, or null.

string
nullable
customer_phone
required

Customer phone number, or null.

string
nullable
status
required

Deprecated combined status. Use order_status, shipping_status and payment_status.

string
order_status
required

Lifecycle status of the order.

string
shipping_status
required

Delivery status.

string
payment_status
required

Payment status.

string
nullable
payment_method
required

Code of the payment method, or null.

string
nullable
subtotal
required

Sum of the line totals.

number
original_subtotal
required

Subtotal before promotions, or null.

number
nullable
shipping_fee
required

Shipping fee charged.

number
original_shipping_fee
required

Shipping fee before promotions, or null.

number
nullable
shipping_discount
required

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

number
nullable
tax
required

Tax amount.

number
discount
required

Total discount.

number
total
required

Amount due.

number
shipping_street
required

Street address to deliver to.

string
shipping_city
required

Province code of the delivery address.

string
shipping_district
required

Deprecated district code, or null.

string
nullable
shipping_ward
required

Ward code, or null.

string
nullable
shipping_postal_code
required

Postal code, or null.

string
nullable
tracking_number
required

Tracking number, or null.

string
nullable
shipping_carrier
required

Name of the carrier, or null.

string
nullable
notes
required

Free-text notes on the order, or null.

string
nullable
created_at
required

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

string
updated_at
required

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

string
can_cancel
required

Whether the order can still be cancelled by the shopper.

boolean

Example

{
"shipment": {
"status": "booked"
}
}

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