Cart

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

Cart is not a separate model in this repo. It is an Order record in cart state, identified by cart = true and a cart_token, and used for storefront item selection, address capture, shipment selection, and checkout readiness.

Parent hierarchy:

• Order Lifecycle
• Cart State And Checkout Readiness
• Cart

Primary implementation paths:

• packages/framework/src/Models/Order.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartItemsController.php
• packages/framework/src/Actions/Cart
• packages/storefront/src/Livewire/Storefront/Cart

What Users Can Do With It

Direct capabilities

Users can:

• create, show, update, and delete carts through the storefront API
• add, update, and remove cart items
• set customer, shipping address, and billing address
• choose shipment-level delivery methods and dates through the shipment flows
• confirm purchase when checkout requirements are satisfied

Indirect capabilities

Other workflows also use Cart:

• cart validation and notifications
• default item shipping preferences on cart load and after address updates when pyle.cart.auto_select_item_fulfillment is enabled (default: false); otherwise keep the legacy single non-pickup service selection after address updates
• abandoned-cart detection and follow-up
• redirect to payment gateway checkout

Things users cannot do directly

This pass did not find a separate packaged admin cart page. Carts surface in the shared package mainly through storefront cart pages and admin order filters, not through a separate admin workspace.

Where It Is Managed

Channel	Role	Notes
Storefront cart pages	Direct	Main packaged UI for cart review and checkout readiness
Storefront API (carts, carts.items, carts.shipments)	Direct	Underlying create, update, item, and shipment operations
Admin orders list	Indirect	Staff can filter or inspect orders that are still carts
Payment gateway redirect	Indirect	Checkout transition happens after cart validation passes

Sources:

• packages/storefront/routes/web.php
• packages/framework/routes/storefront.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php
• packages/framework/src/Http/Controllers/Api/Storefront/CartItemsController.php
• packages/storefront/src/Livewire/Storefront/Cart/PageContent.php

Channel-Level Field Coverage

Cart creation

Creating a cart sets:

• user_id
• customer_id
• optional product_inventory_location_id
• currency
• optional project_number
• optional reference_number
• cart = true

Source:

• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php

Cart update

The cart update flow supports:

• note
• email
• currency
• gift_message
• gift
• shipping_address_id
• billing_address_id
• customer_reference_number
• reference_number
• project_number

Source:

• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php

Checkout-readiness rules

The packaged storefront checkout gate requires:

• a reference number
• at least one item
• a shipping address
• a billing address
• shipping service selection for required items
• a shipment pickup or delivery date
• no critical cart notifications

Source:

• packages/storefront/src/Livewire/Storefront/Cart/SummarySection.php

Configuration And Data Model

Key model characteristics:

• implemented on Order
• identified by cart = true
• keyed for shopper access by cart_token
• can later become a non-cart order when confirmed or reassigned

Important related records:

• items()
• shipments()
• shippingLines()
• criticalNotifications()
• nonCriticalNotifications()

Source:

• packages/framework/src/Models/Order.php

Relationships

Cart directly depends on:

• OrderItem
• OrderShipment
• OrderShippingLine
• customer and address relations on Order

Practical dependents:

• shipment selection
• cart notifications
• payment redirect
• abandoned-cart follow-up

Rules And Downstream Effects

Address and offer side effects

Setting the shipping address can:

• assign the shipping address to the cart
• optionally copy it to billing
• recalculate product offers in cart when configured
• remove invalid items
• fill missing item shipping preferences and apply them through order calculation

Sources:

• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php
• packages/framework/src/Actions/Cart/RecalculateProductOffers.php
• packages/framework/src/Actions/Cart/SelectDefaultOrderItemShippingPreferences.php

Cart-to-order transition

When a cart is confirmed:

• AddToCreditLine runs
• the order can move toward payment/confirmation behavior
• the record stays on the same Order aggregate rather than moving into a separate order table

Sources:

• packages/storefront/src/Livewire/Storefront/Cart/SummarySection.php
• packages/framework/src/Actions/Cart/AddToCreditLine.php

State conversion caveat

If a draft cart is reassigned to an owner through Order/UpdateOrder, the action can flip cart to false and clear existing notifications.

Source:

• packages/framework/src/Actions/Order/UpdateOrder.php

Integrations And Automation

Cart validation

ValidateCart runs pipeline-driven checks and manages notification cleanup when validation should be skipped.

Source:

• packages/framework/src/Actions/Cart/ValidateCart.php

Abandoned-cart workflow

The shared package includes eligibility checks and notification sending for abandoned carts.

Sources:

• packages/framework/src/Models/Order.php
• packages/framework/src/Actions/Order/CheckForAbandonedCarts.php
• packages/framework/src/Actions/Order/SendAbandonedCartNotification.php

Payment gateway redirect

The cart can redirect to Stripe checkout through the storefront API and order checkout-url generation.

Sources:

• packages/framework/src/Http/Controllers/Api/Storefront/CartsController.php
• packages/framework/src/Actions/Stripe/CreateStripeCheckout.php

Where It Appears To End Users

Cart is one of the strongest packaged shopper-facing concepts in the repo.

Shoppers use it through:

• storefront cart pages
• shipment cards
• address blocks
• summary and checkout confirmation

Staff mainly consume it through adjacent order review surfaces and filters.

Current Documentation Takeaways

1. Cart is an Order in cart state, not a separate model.
2. Checkout readiness is enforced by explicit cart rules and notifications, not only by UI affordances.
3. Shipping selection, addresses, and references are part of the cart phase and materially change whether checkout can proceed.

Open Questions

• This first pass did not audit every cart-validation pipe configuration, only the shared validation entrypoint and the main storefront behaviors.