Cart Service — Business & Integration Reference
Overview
The Cart Service manages multi-tenant shopping carts across the Equinox commerce platform. It owns the full cart lifecycle (create, view, update, delete), item management, promotions, shipping, payment, order review and placement, cart merge, and a stateless “virtual cart” flow for subscription renewals. Every cart action runs through a channel-aware, workflow-driven engine whose steps call external capabilities — catalog, inventory, pricing, promotion, tax, shipping, payment, and order — resolved either through marketplace apps or the legacy service registry.
The service is multi-tenant: nearly every operation is scoped to an instanceId (a tenant/store configuration record). It runs as a single serverless function that handles three invocation modes — synchronous API traffic, direct event delivery, and batched event delivery — plus a direct orchestration path for GDPR deletes.
Business Value
| Capability | Outcome |
|---|---|
| Multi-tenant cart management | One deployment serves many stores and brands, each with isolated carts and configuration. |
| Workflow-driven cart actions | Each action runs a configurable workflow; behaviour is tuned per tenant and per channel without code changes. |
| Marketplace app resolution | External providers (e.g. Cin7, Avalara, ShipStation, Stripe) are plugged in as marketplace apps per instance and capability. |
| Full pricing pipeline | Inventory, pricing, promotions, loyalty, tax, and shipping are aggregated into a complete cart calculation breakdown. |
| Virtual cart (stateless) | Subscription renewals get a full preview and checkout without persisting cart state. |
| Cart merge on login | Guest carts are automatically merged into registered-user carts when a shopper signs in. |
| Resilience | Circuit breaker, retry, timeout, fallback, and caching wrap every external provider call. |
| GDPR compliance | Hard-deletes all carts for a user on demand from a compliance orchestration. |
Who Uses It
| Persona | Interaction |
|---|---|
| Storefront / shopper front-end | Calls the Cart Actions APIs (add items, view, promocode, checkout) with a user token. |
| Subscription Service | Calls the Virtual Cart create and checkout endpoints for renewal previews and order placement. |
| Platform admin / operations | Manages instances, cart workflows, the service registry, and marketplace app selections via admin-privileged APIs. |
| User Service | Emits cart-merge events when a guest signs in; Cart Service consumes them to merge carts. |
| Marketplace Service | Emits marketplace app lifecycle events (registered/updated); Cart Service consumes them. |
| Compliance / GDPR orchestrator | Triggers the cart-deletion action directly for a given user. |
| OMS Service | Receives orders created during place-order and virtual checkout. |
Related Resources
- Architecture deep dives and workflow diagrams maintained in the repository.
- Marketplace integration setup and testing guides.
- Backstage catalog entry for service ownership and discovery.
Core Features
| # | Feature | Description |
|---|---|---|
| 1 | Cart actions (17 endpoints) | Add/update/delete items, quantity, shipping, payment, promocode, item addresses, communication preferences, view, minicart, review, place order, delete cart, merge. |
| 2 | Workflow engine | Workflows with 3-tier channel resolution (base then instance default then channel override), circuit breaker, retry, fallback, and saga compensation. |
| 3 | Instance management | Create, read, update, and delete tenant instances, including workflow config, service mappings, and marketplace app selections. |
| 4 | Virtual cart | Stateless subscription-renewal preview and checkout — full calculation pipeline, no persistence. |
| 5 | Calculation engine | Pluggable calculators for subscription, alternate currency, and price-facet breakup. |
| 6 | Marketplace integration | Per-instance, per-capability app selection with optional dynamic install; consumes marketplace app lifecycle events. |
| 7 | Service registry (deprecated) | Legacy adapter configuration for inventory, pricing, tax, shipping, and payment providers. |
| 8 | Extension / plugin validators | External validators loaded through the platform plugin registry (cart, item, merge, instance). |
| 9 | Cart merge | Inbound merge event drives an orchestrated guest-to-registered merge, then emits a merge-completed event. |
| 10 | In-memory mode | An in-memory run mode operates the whole service with no external MongoDB, Redis, or event bus. |
| 11 | Resilience infrastructure | Circuit breaker, cache manager, metrics collector, and timeout manager wrapping every adapter. |
Revision History
2026-08-05 | AN – Page created and uploaded the contents