Design a Bookstore Pricing API with Batch Fetches

Scenario

Design the core Pricing Service for an international online bookstore platform. The service serves product detail pages, checkout funnels, search result listings, and partner book aggregators. A single search result page or recommendation carousel may request real-time pricing for up to 100 books at once.

Prices are dynamic and depend on contextual factors such as customer loyalty tier, delivery country, applied discount codes, and active flash sales.

Requirements

Functional Requirements

• Item & Batch Fetching: Support price retrieval for a single book or batches of up to 250 books per request.
• Pricing Context: Accept pricing context (e.g., user loyalty level, shipping destination country, promo tokens, currency).
• Explicit Freshness: Every returned price must explicitly indicate its calculation timestamp, guaranteed validity window (TTL), and whether it was served from cache or computed fresh.
• Partial Failure Handling: In a batch lookup, failures to resolve specific items (e.g., unlisted book ID, timeout from a regional tax module) must return item-level errors without failing the entire batch.

Non-Functional Requirements

• Throughput: 100,000 requests per second at peak, averaging 10 books per request (1,000,000 item evaluations/sec).
• Latency: Single-item p99 < 25 ms; 100-item batch p99 < 75 ms.
• Catalog Scale: 50 million active titles across 30 regional markets.
• Availability: 99.99% for pricing evaluations.

Key Design Discussion Areas

1. API Protocol & Contract: Contrast HTTP GET with query parameters versus read-only POST for large batch requests (considering URL length limits, intermediate proxy caching, and idempotency). Define the JSON request/response schema with per-item status envelopes.
2. Batch Orchestration & Fan-Out: Detail internal handling of batch requests—request deduplication (e.g., same book requested multiple times in one batch), batch decomposition, bounded concurrency, and deadline propagation to downstream services (base catalog, dynamic promotion engine, tax engine).
3. Contextual Caching: Design a caching topology that handles user personalization without collapsing cache hit ratios. Consider two-tier caching, segment-based cache keys, and cache stampede protection (stale-while-revalidate, single-flight mutexes).
4. Overload Control & Fault Tolerance: Address backpressure, circuit breaking, degraded fallback modes (e.g., serving stale prices marked as unverified for browse traffic vs. strictly blocking stale prices for checkout), and client-side retry amplification.