Sathira Sri Sathara
ad9287b804
- Introduced authenticated shopping state and atomic checkout process without creating orders or payments. - Reused existing components from previous phases including identities, addresses, catalogues, pricing, and inventory. - Developed cart architecture to support one active cart per user with unique items per variant. - Implemented dynamic cart pricing with various precedence rules for promotions and coupons. - Created a wishlist feature that exposes only visible active products without reserving inventory. - Integrated inventory validation to ensure availability of items before adding to cart. - Developed a checkout architecture that locks the cart, revalidates pricing and shipping, and reserves inventory. - Added shipping zones, methods, and rates with configurable options for international shipping and duty/tax boundaries. - Implemented checkout snapshots to capture immutable checkout details. - Introduced idempotency for checkout requests to prevent duplicate processing. - Added functionality for coupon integration and business checkout validation. - Established permissions for managing shipping zones, methods, and rates. - Created comprehensive unit tests covering various aspects of the shopping and checkout processes. - Added cron job for handling checkout expiry reconciliation. - Created migration script to set up new database tables and constraints for carts, checkout sessions, and shipping.
43 lines
2.3 KiB
Markdown
43 lines
2.3 KiB
Markdown
# Shopping and Checkout API
|
|
|
|
All endpoints use `/api/v1` and require authentication unless stated otherwise. Ownership is derived exclusively from the authenticated identity; request bodies never accept `userId`.
|
|
|
|
## Cart
|
|
|
|
- `GET /cart`
|
|
- `POST /cart/items` with `variantId`, `quantity`
|
|
- `PATCH /cart/items/:itemId` with `quantity`; zero removes the item
|
|
- `DELETE /cart/items/:itemId`
|
|
- `DELETE /cart`
|
|
- `PUT /cart/coupon` and `DELETE /cart/coupon`
|
|
|
|
Only one ACTIVE cart exists per user. Adding items does not reserve inventory. Responses revalidate catalogue state, availability, MOQ, business pricing, promotions, coupons, and integer-scaled totals. Unavailable items remain visible with an explanatory status.
|
|
|
|
## Wishlist
|
|
|
|
- `GET /wishlist`
|
|
- `POST /wishlist` with `productId`
|
|
- `DELETE /wishlist/:productId`
|
|
|
|
Wishlist entries are owner-scoped, contain no quantity, and never reserve stock.
|
|
|
|
## Shipping
|
|
|
|
- `POST /shipping/quote` with an owned `addressId`; subtotal is read from the authoritative cart.
|
|
- Admin CRUD: `/admin/shipping/zones`, `/admin/shipping/methods`, `/admin/shipping/rates`.
|
|
|
|
Zones match country, then optional province/district. Rates support schedules, subtotal bands, currency, and configurable free-shipping thresholds. Unsupported destinations return an explicit error. Duty mode is descriptive; tax is zero until authoritative configuration exists.
|
|
|
|
## Checkout
|
|
|
|
- `POST /checkout` requires `Idempotency-Key` and owned shipping/billing address IDs plus a shipping method ID.
|
|
- `GET /checkout/active`
|
|
- `GET /checkout/:id`
|
|
- `POST /checkout/:id/cancel`
|
|
|
|
The server recalculates all prices, shipping, discounts, and availability. Client price/total fields are rejected. Checkout snapshots commerce-critical item/address/shipping data and atomically reserves every item using sorted lock order. The cart becomes `CHECKOUT_LOCKED`. Cancellation or bounded expiry reconciliation releases reservations and restores the cart. Same user/key/payload returns the existing checkout; a changed payload conflicts.
|
|
|
|
Business checkout uses the same cart/session and revalidates active approved status, customer/tier pricing, MOQ, and volume tiers. Business credit is not consumed.
|
|
|
|
No guest cart, Order, Payment, coupon redemption, tax provider, customs calculator, shipment, or delivery workflow exists in Phase 6.
|