Orders API
Endpoints for managing book orders and order history.
List Orders
Get all orders for the authenticated user.
GET /orders
Authentication
Required (Bearer token)
Query Parameters
status(optional) - Filter by status:pending,confirmed,shipped,delivered,cancelledlimit(optional) - Number of results (default: 20)offset(optional) - Pagination offset (default: 0)
Response
{
"orders": [
{
"id": "order-001",
"orderNumber": "ORD-2024-001234",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"status": "confirmed",
"totalCents": 3298,
"itemCount": 2,
"createdAt": "2024-03-20T10:30:00Z",
"updatedAt": "2024-03-20T10:35:00Z"
},
{
"id": "order-002",
"orderNumber": "ORD-2024-001189",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"status": "delivered",
"totalCents": 1599,
"itemCount": 1,
"createdAt": "2024-03-15T14:20:00Z",
"updatedAt": "2024-03-18T09:45:00Z"
}
],
"total": 2,
"limit": 20,
"offset": 0
}
Errors
401 Unauthorized- Not authenticated500 InternalServerError- Server error
Example
curl "https://api.bookwish.app/orders?status=confirmed" \
-H "Authorization: Bearer YOUR_TOKEN"
Create Order
Create a new book order.
POST /orders
Authentication
Required (Bearer token)
Request Body
{
"items": [
{
"inventoryId": "inv-001",
"quantity": 1
},
{
"inventoryId": "inv-002",
"quantity": 2
}
],
"shippingAddress": {
"name": "John Doe",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"country": "US",
"phone": "+1-555-0123"
},
"paymentMethodId": "pm_1234567890"
}
Response
{
"id": "order-003",
"orderNumber": "ORD-2024-001235",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"items": [
{
"id": "item-001",
"inventoryId": "inv-001",
"bookId": "bb0e8400-e29b-41d4-a716-446655440006",
"book": {
"title": "The Catcher in the Rye",
"authors": ["J.D. Salinger"],
"coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
},
"quantity": 1,
"priceCents": 1599,
"storeId": "660e8400-e29b-41d4-a716-446655440001",
"storeName": "Downtown Books"
}
],
"subtotalCents": 1599,
"shippingCents": 599,
"taxCents": 100,
"totalCents": 2298,
"shippingAddress": {
"name": "John Doe",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"country": "US"
},
"createdAt": "2024-03-21T11:00:00Z",
"updatedAt": "2024-03-21T11:00:00Z"
}
Errors
400 ValidationError- Invalid request body or items not available401 Unauthorized- Not authenticated402 PaymentRequired- Payment failed404 NotFound- Inventory items not found500 InternalServerError- Server error
Example
curl -X POST "https://api.bookwish.app/orders" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"items": [{"inventoryId": "inv-001", "quantity": 1}],
"shippingAddress": {
"name": "John Doe",
"addressLine1": "123 Main St",
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"country": "US"
},
"paymentMethodId": "pm_1234567890"
}'
Get Order
Get details of a specific order.
GET /orders/:id
Authentication
Required (Bearer token)
Path Parameters
id- Order ID
Response
{
"id": "order-001",
"orderNumber": "ORD-2024-001234",
"userId": "550e8400-e29b-41d4-a716-446655440000",
"status": "confirmed",
"items": [
{
"id": "item-001",
"inventoryId": "inv-001",
"bookId": "bb0e8400-e29b-41d4-a716-446655440006",
"book": {
"id": "bb0e8400-e29b-41d4-a716-446655440006",
"isbn": "9780316769174",
"title": "The Catcher in the Rye",
"authors": ["J.D. Salinger"],
"coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
},
"quantity": 1,
"priceCents": 1599,
"condition": "new",
"storeId": "660e8400-e29b-41d4-a716-446655440001",
"storeName": "Downtown Books",
"storeSlug": "downtown-books"
},
{
"id": "item-002",
"inventoryId": "inv-002",
"bookId": "bb0e8400-e29b-41d4-a716-446655440007",
"book": {
"id": "bb0e8400-e29b-41d4-a716-446655440007",
"isbn": "9780061120084",
"title": "To Kill a Mockingbird",
"authors": ["Harper Lee"],
"coverUrl": "https://covers.bookwish.app/9780061120084.jpg"
},
"quantity": 1,
"priceCents": 1699,
"condition": "new",
"storeId": "660e8400-e29b-41d4-a716-446655440001",
"storeName": "Downtown Books",
"storeSlug": "downtown-books"
}
],
"subtotalCents": 3298,
"shippingCents": 0,
"taxCents": 264,
"totalCents": 3562,
"shippingAddress": {
"name": "John Doe",
"addressLine1": "123 Main St",
"addressLine2": "Apt 4B",
"city": "Springfield",
"state": "IL",
"postalCode": "62701",
"country": "US",
"phone": "+1-555-0123"
},
"tracking": {
"carrier": "USPS",
"trackingNumber": "9400111899562537393456",
"trackingUrl": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899562537393456"
},
"createdAt": "2024-03-20T10:30:00Z",
"updatedAt": "2024-03-20T14:25:00Z",
"confirmedAt": "2024-03-20T10:35:00Z"
}
Errors
401 Unauthorized- Not authenticated403 Forbidden- Not the order owner404 NotFound- Order not found500 InternalServerError- Server error
Example
curl "https://api.bookwish.app/orders/order-001" \
-H "Authorization: Bearer YOUR_TOKEN"
Cancel Order
Cancel a pending or confirmed order.
POST /orders/:id/cancel
Authentication
Required (Bearer token)
Path Parameters
id- Order ID
Request Body
{
"reason": "Changed my mind"
}
Response
{
"id": "order-001",
"orderNumber": "ORD-2024-001234",
"status": "cancelled",
"cancelledAt": "2024-03-20T15:00:00Z",
"cancellationReason": "Changed my mind"
}
Errors
400 ValidationError- Order cannot be cancelled (already shipped)401 Unauthorized- Not authenticated403 Forbidden- Not the order owner404 NotFound- Order not found500 InternalServerError- Server error
Example
curl -X POST "https://api.bookwish.app/orders/order-001/cancel" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"reason": "Changed my mind"}'
Preview Order Routing
Preview how an order would be routed to stores (without creating the order).
POST /orders/preview
Authentication
Optional (can work for guests)
Request Body
{
"items": [
{
"bookId": "bb0e8400-e29b-41d4-a716-446655440006",
"quantity": 1
}
],
"shippingAddress": {
"postalCode": "62701",
"country": "US"
}
}
Response
{
"routing": {
"items": [
{
"bookId": "bb0e8400-e29b-41d4-a716-446655440006",
"book": {
"title": "The Catcher in the Rye",
"authors": ["J.D. Salinger"],
"coverUrl": "https://covers.bookwish.app/9780316769174.jpg"
},
"quantity": 1,
"availableStores": [
{
"storeId": "660e8400-e29b-41d4-a716-446655440001",
"storeName": "Downtown Books",
"priceCents": 1599,
"condition": "new",
"inStock": true,
"distance": 2.4
},
{
"storeId": "660e8400-e29b-41d4-a716-446655440002",
"storeName": "Book Corner",
"priceCents": 899,
"condition": "used_like_new",
"inStock": true,
"distance": 5.7
}
]
}
],
"estimatedShippingCents": 599,
"estimatedTaxCents": 100
}
}
Errors
400 ValidationError- Invalid request body500 InternalServerError- Server error
Example
curl -X POST "https://api.bookwish.app/orders/preview" \
-H "Content-Type: application/json" \
-d '{
"items": [{"bookId": "bb0e8400-e29b-41d4-a716-446655440006", "quantity": 1}],
"shippingAddress": {"postalCode": "62701", "country": "US"}
}'
Confirm Order from Session
Confirm an order after successful Stripe checkout (called from web checkout success page).
POST /orders/confirm
Authentication
None required
Request Body
{
"sessionId": "cs_test_1234567890"
}
Response
{
"order": {
"id": "order-004",
"orderNumber": "ORD-2024-001236",
"status": "confirmed",
"totalCents": 2298,
"confirmedAt": "2024-03-21T12:00:00Z"
}
}
Errors
400 ValidationError- Invalid or expired session404 NotFound- Order not found500 InternalServerError- Server error
Order Status Values
| Status | Description |
|---|---|
pending | Order created but payment not confirmed |
confirmed | Payment confirmed, order being processed |
shipped | Order has been shipped to customer |
delivered | Order successfully delivered |
cancelled | Order cancelled by user or system |
refunded | Order refunded |
Order Object Fields
| Field | Type | Description |
|---|---|---|
id | string | Unique order identifier |
orderNumber | string | Human-readable order number |
userId | string | Customer's user ID |
status | string | Current order status |
items | array | Array of order items |
subtotalCents | number | Subtotal in cents |
shippingCents | number | Shipping cost in cents |
taxCents | number | Tax amount in cents |
totalCents | number | Total amount in cents |
shippingAddress | object | Shipping address details |
tracking | object | Tracking information (if available) |
createdAt | string | Creation timestamp (ISO 8601) |
updatedAt | string | Last update timestamp (ISO 8601) |
confirmedAt | string | Confirmation timestamp (ISO 8601) |
cancelledAt | string | Cancellation timestamp (ISO 8601) |