Shopping cart operations with 3-layer architecture: API Gateway -> Cart & Checkout Orchestrator -> Core Microservices
View Postman DocumentationComplete flow with validation, pricing, promotions, and cart computation (10 steps)
{
"operations": [
{ "op": "SET", "product_id": "...", "variant_id": "...", "quantity": 2, "addons": [...] },
{ "op": "ADD", "product_id": "...", "quantity": 1 },
{ "op": "UPDATE", "item_id": "...", "quantity": 3 },
{ "op": "DELETE", "item_id": "..." }
]
}POST /cart/items
POST /cart/items
Orchestrates 10 service calls (with parallel execution)
POST /api/carts/find-or-create
Get existing cart or create new one in single call
GET /api/products/search
Validate products, addons & variants
POST /api/inventory/check-availability
Check stock availability
POST /api/shipping/calculate-rate
Calculate delivery charges (conditional)
GET /merchant/api/v1/domains/:domain_id/stores/:store_id
Check store active/online status, basic details
GET /api/v1/domains/:domain_id/stores/:store_id/tax_settings
Get store tax configuration
POST /api/promotions/applicable
Get auto-applicable promotions, combo offers
POST /api/carts/:cart_id/items/batch
Apply batch operations (SET, ADD, UPDATE, DELETE)
POST /api/carts/:cart_id/compute
Recalculate cart totals with all charges and discounts
POST /api/caching/set
Key: cart:{cart_id}:computed | TTL: 1800s (30 mins)
{
"success": true,
"operations_applied": 4,
"results": [
{ "operation": "SET", "status": "SUCCESS", "action_taken": "ADDED", "item": {...} },
{ "operation": "UPDATE", "status": "SUCCESS", "item_id": "..." },
{ "operation": "ADD", "status": "SUCCESS", "item": {...} },
{ "operation": "DELETE", "status": "FAILED", "error": "Item not found", "item_id": "..." }
],
"cart": { ...full computed cart... },
"coupon_applied": [...]
}Lightweight flow - skips validation and computation, only applies operations (3 steps)
{
"operations": [
{ "op": "SET", "product_id": "...", "variant_id": "...", "quantity": 2, "addons": [...] },
{ "op": "ADD", "product_id": "...", "quantity": 1 },
{ "op": "UPDATE", "item_id": "...", "quantity": 3 },
{ "op": "DELETE", "item_id": "..." }
]
}POST /cart/items
POST /cart/items
Lightweight flow - 3 sequential calls only
POST /api/carts/find-or-create
Get existing cart or create new one
POST /api/carts/:cart_id/items/batch
Apply batch operations directly
POST /api/caching/set
Key: cart:{cart_id}:computed | TTL: 1800s
{
"success": true,
"operations_applied": 4,
"results": [
{ "operation": "SET", "status": "SUCCESS", "action_taken": "ADDED", "item": {...} },
{ "operation": "UPDATE", "status": "SUCCESS", "item_id": "..." },
{ "operation": "ADD", "status": "SUCCESS", "item": {...} },
{ "operation": "DELETE", "status": "FAILED", "error": "Item not found", "item_id": "..." }
],
"cart": { ...full computed cart... },
"coupon_applied": [...]
}Update coupons, addresses, tips, delivery, payment, gift wrap, instructions (12 steps)
{
"coupons": [{ "code": "SAVE20" }],
"address": {
"shipping_address": { "address_id": "addr_456" },
"billing_address": { "same_as_shipping": false, "address_id": "addr_456" }
},
"tips": { "amount": 50, "currency": "INR", "description": "Thank you tip" },
"delivery_option": { "delivery_option_id": "deliv_opt_123" },
"delivery_preference": {
"scheduled": { "date": "2025-11-10", "slot": { "id": "slot_today_1", "label": "6:00 PM - 6:30 PM" } },
"immediate": null
},
"pickup_point": { "pickup_point_id": "pickup-point-option-id" },
"payment_method": { "payment_method_id": "pay_method_789" },
"gift_wrap": { "id": "gift_wrap_standard", "message": "Happy Birthday!" },
"special_instructions": { "instructions": "Please leave at front door." }
}PUT /cart
PUT /cart
Orchestrates 12 service calls (with parallel validation)
GET /api/carts/:cart_id
Get existing cart
POST /api/coupons/validate
Validate coupon codes (if provided)
GET /api/addresses/:address_id
Validate shipping/billing addresses
GET /api/delivery-options/:id
Validate delivery option
GET /api/pickup-points/:id
Validate pickup point
GET /api/payment-methods/:id
Validate payment method
GET /api/gift-wrap-options/:id
Validate gift wrap option & pricing
PUT /api/carts/:cart_id/options
Update cart with validated options
POST /api/shipping/calculate-rate
Calculate delivery charges (if delivery option changed)
POST /api/promotions/applicable
Recalculate promotions based on new cart state
POST /api/carts/:cart_id/compute
Recalculate totals with tips, gift wrap, delivery
POST /api/caching/set
Key: cart:{cart_id}:computed | TTL: 1800s (30 mins)
{
"success": true,
"cart": { ...full computed cart with updated options... },
"validations": {
"coupon": { "status": "VALID", "discount": 200 },
"address": { "status": "VALID" },
"delivery_option": { "status": "VALID", "charge": 50 },
"payment_method": { "status": "VALID" }
}
}Retrieve cart with full recomputation - validates items, pricing, inventory, promotions (11 steps)
?compute=true
(default)
GET /cart
GET /cart
Orchestrates 11 service calls (with parallel validation)
GET /api/carts/:cart_id
Get existing cart
GET /api/products/search
Validate products still active with current pricing
POST /api/inventory/check-availability
Check stock availability for all items
GET /merchant/api/v1/.../stores/:store_id
Check store is active
GET /api/v1/.../tax_settings
Get store tax configuration
GET /api/delivery-options/:id
Validate delivery option (if set)
POST /api/shipping/calculate-rate
Calculate delivery charges (if delivery option selected)
POST /api/promotions/applicable
Get auto-applicable promotions, combo offers
POST /api/coupons/validate
Re-validate any applied coupons are still valid
POST /api/carts/:cart_id/compute
Recalculate totals: subtotal, discounts, taxes, delivery, tips, gift wrap, net_payable
POST /api/caching/set
Key: cart:{cart_id}:computed | TTL: 1800s (30 mins)
{
"success": true,
"cart": {
"cart_id": "...",
"items": [...],
"coupons_applied": [...],
"address": { "shipping": {...}, "billing": {...} },
"delivery_option": {...},
"tips": {...},
"gift_wrap": {...},
"totals": {
"subtotal": 1000,
"discount": -200,
"tax": 50,
"delivery_charge": 50,
"tips": 50,
"gift_wrap": 25,
"net_payable": 975
}
},
"inventory_status": [
{ "product_id": "...", "available": true, "quantity_available": 10 }
],
"warnings": []
}Fast retrieval from cache - returns last computed state without recomputation (2 steps)
?compute=false
(returns cached cart)
GET /cart?compute=false
GET /cart?compute=false
Fast path - 2 steps max (cache first, fallback to DB)
GET /api/caching/get
Key: cart:{cart_id}:computed
Try to get from cache first (fast path)
GET /api/carts/:cart_id
Get basic cart from DB without computation
{
"success": true,
"from_cache": true,
"cart": { ...cached computed cart... },
"cache_age_seconds": 120
}Delete entire cart - removes all items, clears cache, releases inventory reservations (3 steps)
DELETE /cart
DELETE /cart
Delete cart and cleanup resources - 3 steps
DELETE /api/carts/:cart_id
Delete cart from database
DELETE /api/caching/delete
Key: cart:{cart_id}:computed
POST /api/inventory/release-reservations
Release any held inventory reservations
{
"success": true,
"message": "Cart deleted successfully",
"cart_id": "..."
}Quick purchase flow - creates cart and proceeds directly to checkout (3 steps)
{
"operations": [
{ "op": "ADD", "product_id": "...", "quantity": 1 }
]
}POST /buy-now
POST /buy-now
Express checkout flow - 3 sequential calls
POST /api/carts/find-or-create
Get existing cart or create new one
POST /api/carts/:cart_id/items/batch
Apply cart item operations
POST /api/caching/set
Key: cart:{cart_id}:computed | TTL: 1800s
{
"success": true,
"operations_applied": 1,
"results": [
{ "operation": "ADD", "status": "SUCCESS", "item": {...} }
],
"cart": { ...full computed cart... },
"coupon_applied": [...]
}Converts cart to order with multi-payment support: GATEWAY, WALLET, MANUAL/COD (13 steps)
{
"payment_instruction": [
{ "full_amount": false, "amount": 150, "currency": "INR", "payment_mode": "GATEWAY", "gateway": "PHONEPE", "client_callback_url": "https://..." },
{ "full_amount": false, "amount": 50, "currency": "INR", "payment_mode": "WALLET", "gateway": "STORE-WALLET", "meta": { "wallet_id": "...", "otp": "..." } },
{ "full_amount": false, "amount": 50, "currency": "INR", "payment_mode": "MANUAL", "gateway": "COD" }
],
"total_order_amount": 250,
"multiple_payment_methods": true,
"order_initiated_from": "WEB",
"device": { "type": "MOBILE", "fingerprint": "fp_hash_456", "ip_address": "192.168.1.1", "user_agent": "Mozilla/5.0", "timezone": "Asia/Kolkata" }
}POST /cart/place-order
POST /cart/place-order
Orchestrates multi-phase order flow (Phase 1: Order Creation, Phase 2: Post-Payment)
GET /api/carts/:cart_id
Get cart with all items and options
POST /api/inventory/check-availability
Final stock check (strict: true)
GET /api/products/search
Compare current vs cart prices
POST /api/coupons/validate
Re-validate coupons still applicable
Σ payment_instruction.amount == total_order_amount
Ensure payment amounts match
POST /api/inventory/reserve
TTL: 900s (15 min) - temporary hold on stock
POST /api/orders
Create master order (type: MASTER, status: PENDING)
POST /api/orders/:master_order_id/sub-orders
Create sub-orders per store/seller
PUT /api/orders/:order_id/payment-status
Set payment status: PENDING
POST /api/payments/initiate
GATEWAY (PhonePe, Razorpay)
→ redirect_url, gateway_order_id
POST /api/payments/initiate
WALLET (Store Wallet)
→ Instant debit with OTP
POST /api/payments/initiate
MANUAL (COD)
→ Auto-success, collect later
Triggered after payment confirmation webhook/callback
POST /api/inventory/deduct
Convert reservation to actual deduction
POST /api/coupons/used
Mark coupons as used for this order
DELETE /api/carts/:cart_id
Clear cart after successful order
DELETE /api/caching/delete
Key: cart:{cart_id}:computed
POST /api/notifications/send
Order confirmation: EMAIL, SMS, PUSH
POST /api/events/publish
Event: ORDER_PLACED + device fingerprint
{
"success": true,
"order": {
"id": "order_999",
"number": "ORD-2025-1234",
"order_status": "PENDING",
"payment_status": "PENDING",
"total": 250,
"currency": "INR",
"sub_orders": [
{ "id": "sub_order_001", "number": "ORD-2025-1234-01", "store_id": "store_123", "order_status": "PENDING", "total": 250 }
]
},
"payment": [
{ "id": "pay_001", "status": "PENDING", "payment_mode": "GATEWAY", "gateway": "PHONEPE", "amount": 150, "redirect_url": "https://phonepe.com/pay/..." },
{ "id": "pay_002", "status": "SUCCESS", "payment_mode": "WALLET", "gateway": "STORE-WALLET", "amount": 50 },
{ "id": "pay_003", "status": "SUCCESS", "payment_mode": "MANUAL", "gateway": "COD", "amount": 50 }
]
}Intelligent product recommendations: complementary, bundles, upsells, threshold offers, reminders (9 steps)
GET /cart/suggestions
Coordinates suggestion generation from multiple recommendation sources
GET /api/carts/:cart_id
Get current cart items for analysis
POST /api/recommendations/complementary
Frequently Bought Together
POST /api/bundles/applicable
Bundle Deals
POST /api/recommendations/upsells
Upgrade Your Items
POST /api/promotions/threshold-offers
Free Delivery / Discounts
POST /api/recommendations/reminders
Did You Forget?
POST /api/products/search
Fetch full product details: images, prices, stock status
POST /api/inventory/check-availability
Filter out out-of-stock suggestions
Assemble & Rank Suggestions
Combine, deduplicate, rank by relevance/conversion probability
{
"success": true,
"suggestions": [
{
"type": "COMPLEMENTARY",
"title": "Frequently Bought Together",
"items": [{ "product_id": "prod_456", "name": "Phone Case", "price": 299, "reason": "80% of customers bought this" }]
},
{
"type": "THRESHOLD_BASED",
"title": "Add ₹99 more for FREE Delivery!",
"threshold": { "target_amount": 599, "current_amount": 500, "remaining_amount": 99, "benefit": "FREE_DELIVERY" },
"items": [{ "product_id": "prod_789", "name": "Screen Protector", "price": 149 }]
},
{
"type": "BUNDLE",
"title": "Bundle Deal - Save 25%",
"bundle": { "bundle_id": "bundle_123", "name": "Complete Accessory Kit", "bundle_price": 899, "savings": 301 },
"items": [{ "product_id": "prod_456", "name": "Phone Case" }, { "product_id": "prod_789", "name": "Screen Protector" }]
},
{
"type": "UPSELL",
"title": "Upgrade Your Items",
"items": [{ "product_id": "prod_premium_456", "name": "Premium Leather Case", "price": 799, "reason": "Better durability" }]
},
{
"type": "REMINDER",
"title": "Did You Forget?",
"items": [
{ "product_id": "prod_saved_123", "name": "Bluetooth Earbuds", "price": 1299, "source": "WISHLIST" },
{ "product_id": "prod_viewed_456", "name": "Power Bank", "price": 899, "source": "RECENTLY_VIEWED" }
]
}
],
"meta": { "total_suggestions": 7, "suggestion_types": ["COMPLEMENTARY", "THRESHOLD_BASED", "BUNDLE", "UPSELL", "REMINDER"] }
}Find/create, batch ops, compute, options
Product validation, pricing
Stock availability, reservations
Promotions, coupons, offers
Store, tax, delivery, pickup, gift wrap
Delivery rate calculation
Address validation
Payment method validation
Redis cache for cart
Master orders, sub-orders, seller orders
Points redemption, rewards
Email, SMS, Push notifications
Order events, analytics tracking
AI-powered suggestions, upsells, reminders
| Method | Endpoint | Variant | Steps | Description |
|---|---|---|---|---|
| POST | /cart/items | Full | 10 | Add/update items with full validation & computation |
| POST | /cart/items | Lite | 3 | Add/update items without computation |
| PUT | /cart | Update | 12 | Update cart options (coupons, address, tips, etc.) |
| GET | /cart | Full | 11 | Get cart with full recomputation |
| GET | /cart?compute=false | Cached | 2 | Get cached cart (fast) |
| DELETE | /cart | Delete | 3 | Delete cart and cleanup |
| POST | /buy-now | Express | 3 | Quick purchase / express checkout |
| POST | /cart/place-order | Checkout | 13 | Convert cart to order with multi-payment (2 phases) |
| GET | /cart/suggestions | AI-Powered | 9 | Smart suggestions: complementary, bundles, upsells, reminders |
Orchestra Internal API Mapping - Cart Module
Last Updated: December 2025