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,
  "items": [
    {
      "id": "guid",
      "productVariantId": "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.

Order Statuses

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

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.