Orders

After a successful checkout and payment, an order is created. Authenticated users can view their order history and details.

Order Lifecycle

List User Orders

GET /api/storefront/orders
Authorization: Bearer <token>

Response:

[
  {
    "id": "guid",
    "orderNumber": "ORD-20260323-001",
    "orderDate": "2026-03-23T14:30:00Z",
    "status": "Processing",
    "paymentMethod": "stripe",
    "paymentStatus": "Paid",
    "totalAmount": 47.98,
    "items": [
      {
        "productVariantId": "guid",
        "quantity": 2,
        "unitPrice": 29.99,
        "totalPrice": 59.98
      }
    ]
  }
]

Orders are sorted by date, newest first.

Get Order Detail

GET /api/storefront/orders/{orderId}/detail
Authorization: Bearer <token>

Response:

{
  "id": "guid",
  "orderNumber": "ORD-20260323-001",
  "orderDate": "2026-03-23T14:30:00Z",
  "status": "Processing",
  "paymentMethod": "stripe",
  "paymentStatus": "Paid",
  "notes": null,
  "shippingAddress": "123 Main St, New York, NY 10001, US",
  "billingAddress": "123 Main St, New York, NY 10001, US",
  "subTotal": 59.98,
  "shippingCost": 5.99,
  "taxAmount": 0,
  "discountAmount": 12.00,
  "totalAmount": 53.97,
  "currencyCode": "USD",
  "shipments": [
    {
      "status": "shipped",
      "carrierName": "UPS",
      "trackingNumber": "1Z999AA10123456784",
      "estimatedShipDate": "2026-03-24T00:00:00Z",
      "shippedAt": "2026-03-24T09:12:00Z"
    }
  ],
  "items": [
    {
      "id": "guid",
      "productVariantId": "guid",
      "productId": "guid",
      "sku": "CT-WHT-M",
      "productName": "Classic T-Shirt",
      "quantity": 2,
      "unitPrice": 29.99,
      "totalPrice": 59.98,
      "imageUrl": "https://api.example.com/media/product-images/ct-white.png"
    }
  ]
}

The detail endpoint includes localized product names and resolved image URLs for displaying a rich order summary.

• shipments — how the order is being fulfilled, one entry per warehouse it ships from, oldest first; empty until fulfilment has started, cancelled fulfilments left out. status is one of pending, acknowledged, inProduction, picking, packing, readyToShip, shipped, delivered, onHold. Show progress from these together with the order's own status, which may lag behind (an order can still be Processing while one parcel is already shipped).
• discountAmount is what was taken off: subTotal + shippingCost − totalAmount. Where prices include tax, taxAmount is information only — it is already inside subTotal and is not part of the sum.
• imageUrl is the variant's primary image — the same one the basket showed.
• Bundle components are listed as lines with a parentOrderItemId; show (and sum) the lines without one.

Order Lookup Without an Account

GET /api/storefront/orders/track?orderNumber=ORD-20260323-001&email=customer@example.com
GET /api/storefront/orders/track?orderNumber=ORD-20260323-001&phone=05551112233

For guest orders: the order number plus the e-mail or phone given at checkout returns the same detail shape (without notes). A mismatch is answered with 404 whether or not the order number exists, so the endpoint cannot be used to probe for order numbers. Phone numbers are compared on their last ten digits, so +90 555…, 0555… and 555… all match.

Order Statuses

Status	Description
Pending	Order created, payment processing
Processing	Payment confirmed, being prepared
Shipped	Handed to carrier
Delivered	Successfully delivered
Cancelled	Order cancelled
Returned	Returned by the customer

Authorization

Orders are scoped to the authenticated user. A user can only view their own orders. Attempting to access another user's order returns 403 Forbidden.

Order Tracking

The current API returns order status. For detailed shipment tracking (carrier, tracking number), check the order's fulfillment status via the order detail endpoint.