core/docs/checkout.md

Checkout — Design Notes

Status: design finalized, not yet built. This is the design spec for Modules\Core\Checkout\Services\CheckoutService, plus the three-stage lifecycle model it's part of. Nothing in this document is implemented yet.

---

Three-stage lifecycle: Cart → Checkout → Order

Each stage is its own concern, not a phase inside a shared one — matching the pattern already established this session (Recovery was split out from Cart specifically because abandonment detection is a different lifecycle stage than line-item mutation, even though it reads Cart state).

• Cart — line items, coupons, save-for-later (docs/cart.md). Ends the moment Cart::createOrder() is called.
• Checkout — the placement moment itself: setting addresses, selecting a shipping option, placing the order. Starts where Cart ends, ends the instant an Order exists. This document.
• Order — everything after an order exists: status transitions (Order::status, changed via the Filament admin EditOrder page — always staff-driven, never part of checkout itself), fulfillment/shipment tracking. Named and scoped here, not yet built — same status as Recovery before it existed as real code.

Modules\Core\Checkout\Events\OrderPlaced (see below) is the handoff point: Checkout dispatches it the moment an order exists; Order's own listeners (not built yet) would be what reacts to it — e.g. sending a confirmation email, initializing whatever Order needs to initialize. Checkout itself has no opinion about what happens after OrderPlaced fires.

Where Order would likely absorb work that currently lives under Shipping

Modules\Core\Shipping's Shipment/ShipmentInfo models are already order-scoped (Shipment::order(): BelongsTo), and PollShipmentTrackingJob/ ShipmentStatusUpdatedByCarrier are fulfillment/tracking concerns that happen entirely after an order exists — conceptually closer to Order than to Shipping's actual job (carrier rate quoting, ShippingRateInterface drivers, ShippingManifest). Not decided whether/when this gets moved; noted here so the boundary is visible when Order is actually scoped.

---

CheckoutService

Mirrors Modules\Core\Cart\Services\CartService's shape (see docs/cart.md) — one boboko-owned API a storefront calls, keeping Lunar's own Cart/ShippingManifest primitives an implementation detail.

Method	Wraps	Dispatches
setShippingAddress(array|Addressable $address)	Cart::setShippingAddress()	ShippingAddressSet($cart, $address)
setBillingAddress(array|Addressable $address)	Cart::setBillingAddress()	BillingAddressSet($cart, $address)
getShippingOptions()	ShippingManifest::getOptions($cart)	— (read-only)
selectShippingOption(string $identifier)	Cart::setShippingOption()	ShippingOptionSelected($cart, $option) — throws InvalidShippingOptionException if $identifier doesn't resolve
placeOrder(string $fingerprint)	Cart::checkFingerprint() then Cart::createOrder()	OrderPlaced($order)

getShippingOptions() — already fully backed by the merged Shipping-Carriers work

ShippingManifest::getOptions($cart) runs every registered ShippingRateInterface driver through a pipeline — this already includes ACS/Box Now live-rate quoting (Modules\Core\Shipping\Carriers\Acs\AcsRateDriver/BoxNowRateDriver, merged from the Shipping-Carriers branch) alongside table-rate-shipping's own flat-rate/free-shipping/ collection drivers. CheckoutService doesn't need to build any rate-resolution logic — it's a thin pass-through to what already exists and works.

placeOrder() — fingerprint check is mandatory, not optional

placeOrder(string $fingerprint): Order requires the fingerprint the shopper's last-seen cart total was built from (Cart::fingerprint()) as a parameter — not an optional after-the-fact check a caller might forget. Cart::checkFingerprint() throws Lunar's own FingerprintMismatchException if the cart's contents/total changed since that fingerprint was generated (a line's price changed, stock adjusted the total, another tab modified the cart), forcing re-confirmation instead of silently placing an order at a different total than what the shopper approved.

No exception wrapping — same reasoning as CartService

Confirmed from source: Lunar\Validation\Cart\ValidateCartForOrderCreation (the validator Cart::createOrder() runs via config('lunar.cart.validators.order_create')) already throws Lunar\Exceptions\Carts\CartException with a field-keyed MessageBag ($exception->errors()) — billing/shipping address completeness, missing shipping option, duplicate-order guard. This is already the right shape for a storefront to catch and render as form errors directly; wrapping it in a boboko-owned exception type would add indirection with identical semantics, the same call made for CartService's cart-line exceptions.

FingerprintMismatchException (from the mandatory fingerprint check above) propagates as-is for the same reason.

One genuine exception to this rule: selectShippingOption() throws Modules\Core\Checkout\Exceptions\InvalidShippingOptionException when $identifier doesn't resolve to a real option (ShippingManifest::getOption() just returns null — Lunar has no matching exception type here to propagate, unlike CartException/FingerprintMismatchException above). Same reasoning as Modules\Core\Cart\Exceptions\InvalidCouponException for Discounts::validateCoupon(), which also just returns a bool with nothing to reuse. Confirmed live: an invalid identifier previously returned the cart unchanged with no signal at all — fixed to throw instead, verified via a real container test.

Validated from source: the real precondition chain

ValidateCartForOrderCreation::validate(), read directly from vendor/lunarphp/core:

1. No completed order already exists on this cart (duplicate-order guard).
2. A billing address is set and passes country_id/first_name/line_one/city/postcode required-field validation.
3. If the cart isShippable() (has at least one non-digital line):
   • A shipping option must already be selected (Cart::getShippingOption() — which only resolves anything once shippingAddress->shipping_option has been persisted via selectShippingOption(), confirmed from Lunar\Base\ShippingManifest::getShippingOption()).
   • Unless that option is collect/pickup ($shippingOption->collect), a shipping address is also required and validated the same way as billing.

This is why CheckoutService's methods exist in the order they're listed above — a storefront checkout flow has to drive them roughly in that sequence for placeOrder() to ever succeed.

---

Events — richer payload than CartService's, deliberately

Modules\Core\Checkout\Events: ShippingAddressSet, BillingAddressSet, ShippingOptionSelected, OrderPlaced.

Unlike CartService's events (which carry a plain Cart/CartLine model reference — see docs/cart.md), these carry richer, already-resolved payload — e.g. ShippingOptionSelected includes the resolved ShippingOption (name, price, carrier identifier), not just the string identifier a listener would have to re-resolve. Deliberate divergence from CartService's convention: a live-priced shipping quote or a submitted address is meaningfully more expensive/awkward for a listener to re-derive later than a CartLine model reference is.

Why this matters beyond Checkout itself: the Analytics survey (docs/scratch/ analytics-feature-survey.html) found conversion-funnel tracking (product view → add to cart → checkout → purchase) entirely missing, with zero underlying data captured anywhere. The Checkout survey separately flagged "abandoned-checkout stage tracking (email captured vs. shipping selected vs. payment started)" as missing. One event per real state transition here — not just a single OrderPlaced at the end — is what gives a future analytics/reporting listener (not built) the funnel-stage data neither gap currently has anything to build on.

None of these have a listener yet. Same status as CartService's events — dispatched, unconsumed, built so something downstream has a hook to attach to.

---

Explicitly out of scope for CheckoutService

• Order-status-changed events — post-placement, staff-driven (Order::status changes via the Filament admin EditOrder page, never through checkout). Belongs to Order (see above), not Checkout.
• Order confirmation email — needs OrderPlaced as a trigger, but actual sending is separate infrastructure, same "detection/signal only, sending is a later concern" deferral already applied to Recovery (docs/recovery-strategies.md).
• Guest order tracking/lookup — a separate storefront feature, not part of the placement flow itself.
• Payment — authorizing/capturing a transaction against the placed order. Genuinely separate from Checkout as scoped here; CheckoutService::placeOrder() produces an Order, what happens to pay for it is out of this document's scope.