Place Order with Payment (Customer)
Creates a new order and initiates payment processing. Returns a client secret for completing payment on the client side (e.g., using Stripe).
Request Body
Customer identifier (must match authenticated user)
Selected delivery method identifier
Array of order items (productId, quantity, variantId if applicable)
Optional order notes or special instructions
Response
Payment client secret for completing payment (e.g., Stripe client secret)
Response Codes
200 OK - Order created, payment initiated400 Bad Request - Invalid order data or insufficient stock404 Not Found - Customer, delivery method, or product not found500 Internal Server Error - Payment processing error
Examples
curl -X POST "https://your-server.com/api/orders/with-payment" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customerId": "customer-uuid",
"deliveryMethodId": "delivery-method-uuid",
"deliveryAddress": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA"
},
"items": [
{
"productId": "product-uuid-1",
"quantity": 2,
"variantId": null
},
{
"productId": "product-uuid-2",
"quantity": 1,
"variantId": "variant-uuid"
}
],
"notes": "Please ring doorbell upon delivery"
}'
Success Response Example
{
"orderId": "order-uuid",
"clientSecret": "pi_1234567890_secret_abcdefghijklmnop",
"totalAmount": 459.98
}
Error Response Examples
Insufficient Stock (400 Bad Request):
"Product 'Premium Headphones' has insufficient stock. Available: 1, Requested: 2"
"Delivery method not found"
"Failed to initialize payment: [error details]"
Place Order without Payment (Customer)
Creates an order for cash-on-delivery or other non-prepaid payment methods.
Request Body
Selected delivery method identifier
Response Codes
204 No Content - Order created successfully400 Bad Request - Invalid order data404 Not Found - Customer, delivery method, or product not found
Examples
curl -X POST "https://your-server.com/api/orders" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"customerId": "customer-uuid",
"deliveryMethodId": "delivery-method-uuid",
"deliveryAddress": {
"street": "123 Main St",
"city": "New York",
"state": "NY",
"zipCode": "10001",
"country": "USA"
},
"items": [
{
"productId": "product-uuid",
"quantity": 1
}
]
}'
Mark Order as Paid (Customer)
Marks an order as paid after successful payment confirmation. Typically called after payment provider confirms payment.
Path Parameters
Response Codes
204 No Content - Order marked as paid400 Bad Request - Order already paid or payment failed
Examples
curl -X PATCH "https://your-server.com/api/orders/order-uuid/paid" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Error Response Examples
Already Paid (400 Bad Request):
"Order has already been marked as paid"
Order Creation Flow
Add Items to Cart
Customer browses products and adds items to shopping cart
Proceed to Checkout
Customer reviews cart and proceeds to checkout
Select Delivery
Customer selects delivery method and provides delivery address
Choose Payment Method
Customer chooses online payment or cash-on-delivery
Create Order
Call /api/orders/with-payment (online) or /api/orders (COD)
Complete Payment (if online)
Use client secret to complete payment with payment provider
Confirm Payment
Call /api/orders/{orderId}/paid after payment success
Order Confirmation
Customer receives order confirmation and tracking information
Order Validation
The system validates all order items before creation:
- Product availability
- Stock levels
- Price accuracy
- Delivery method compatibility
Orders cannot be modified after creation. Customers must cancel and create a new order for changes.
Payment Integration
The order creation with payment typically integrates with payment providers like Stripe:
- Server creates order and payment intent
- Server returns client secret
- Client uses secret to complete payment
- Payment provider confirms payment
- Client calls
/paid endpoint to finalize order
Stripe Example
// 1. Create order and get client secret
const orderResponse = await fetch('/api/orders/with-payment', {...});
const { orderId, clientSecret } = await orderResponse.json();
// 2. Confirm payment with Stripe
const stripe = Stripe('pk_test_...');
const { error, paymentIntent } = await stripe.confirmCardPayment(clientSecret, {
payment_method: {
card: cardElement,
billing_details: { name: 'Customer Name' }
}
});
// 3. Mark order as paid
if (paymentIntent.status === 'succeeded') {
await fetch(`/api/orders/${orderId}/paid`, {
method: 'PATCH',
headers: { 'Authorization': `Bearer ${token}` }
});
}