Skip to content

Architecture

Database schema, service contracts, totals system, and validation rules

Database Schema

The Quote module manages 8 core tables that store shopping cart data.

Table Purpose Key Columns
quote Main cart entity entity_id, store_id, customer_id, is_active, grand_total
quote_item Cart line items item_id, quote_id, product_id, sku, qty, price, row_total
quote_address Billing/shipping addresses address_id, quote_id, address_type, street, city, country_id
quote_address_item Address-specific item data address_item_id, quote_address_id, quote_item_id
quote_item_option Product options per item option_id, item_id, product_id, code, value
quote_payment Payment method selection payment_id, quote_id, method
quote_shipping_rate Available shipping rates rate_id, address_id, carrier, method, price
quote_id_mask Guest cart token mapping entity_id, quote_id, masked_id

Service Contracts

Cart Management

  • I
    CartRepositoryInterface

    CRUD operations for quote entities

  • I
    CartManagementInterface

    Cart creation, customer assignment, order placement

  • I
    CartItemRepositoryInterface

    Cart item add/update/delete operations

Totals & Pricing

  • I
    CartTotalRepositoryInterface

    Retrieve calculated cart totals

  • I
    CartTotalManagementInterface

    Collect and update totals

  • I
    CouponManagementInterface

    Apply/remove coupon codes

Address Management

  • I
    BillingAddressManagementInterface

    Get/set billing address

  • I
    ShippingMethodManagementInterface

    Get available shipping methods

  • I
    ShipmentEstimationInterface

    Estimate shipping by address

Guest Cart APIs

  • I
    GuestCartManagementInterface

    Anonymous cart operations

  • I
    GuestCartRepositoryInterface

    Guest cart retrieval by masked ID

  • I
    MaskedQuoteIdToQuoteIdInterface

    Resolve masked ID to quote ID

Totals Collection System

The totals collector system is extensible and runs collectors in a defined order to calculate cart totals.

Default Collector Order

  1. 1 Subtotal (item prices)
  2. 2 Discount (coupon/rules)
  3. 3 Shipping (carrier rates)
  4. 4 Tax (calculated totals)
  5. 5 Grand Total (final sum)

Adding Custom Collector

<!-- etc/sales.xml -->
<section name="quote">
    <group name="totals">
        <collectors>
            <collector
                name="custom_fee"
                class="Vendor\Module\Model\Total\CustomFee"
                after="subtotal"
                before="grand_total"
            />
        </collectors>
    </group>
</section>

Performance Note

Totals are recollected automatically when items, addresses, or coupons change. Use $quote->setTotalsCollectedFlag(true) to skip recollection when you know totals are current.

Validation Rules

The Quote module uses a composable validation system defined in di.xml.

Rule Validates Error Message
AllowedCountryValidationRule Address country is allowed for shipping/billing Some addresses can't be used due to country configurations
ShippingAddressValidationRule Required shipping address fields Please check the shipping address information
ShippingMethodValidationRule Shipping method is selected The shipping method is missing
BillingAddressValidationRule Required billing address fields Please check the billing address information
PaymentMethodValidationRule Payment method is valid Enter a valid payment method
MinimumAmountValidationRule Cart meets minimum order amount Minimum order amount not reached

Adding Custom Validation

// di.xml
<type name="Magento\Quote\Model\ValidationRules\QuoteValidationComposite">
    <arguments>
        <argument name="validationRules" xsi:type="array">
            <item name="custom_rule" xsi:type="object">
                Vendor\Module\Model\ValidationRules\CustomRule
            </item>
        </argument>
    </arguments>
</type>

REST API Structure

The Quote module exposes 63 REST endpoints across three access levels.

Admin Endpoints (21)

Full cart management by ID

  • /V1/carts/:cartId
  • /V1/carts/:cartId/items
  • /V1/carts/:cartId/billing-address
  • /V1/carts/:cartId/coupons
  • /V1/carts/:cartId/totals

Customer Endpoints (21)

Self-service via /mine

  • /V1/carts/mine
  • /V1/carts/mine/items
  • /V1/carts/mine/billing-address
  • /V1/carts/mine/coupons
  • /V1/carts/mine/totals

Guest Endpoints (21)

Anonymous via masked ID

  • /V1/guest-carts/:cartId
  • /V1/guest-carts/:cartId/items
  • /V1/guest-carts/:cartId/billing-address
  • /V1/guest-carts/:cartId/coupons
  • /V1/guest-carts/:cartId/totals

Directory Structure

module-quote/
├── Api/                        # Service contracts (38 interfaces)
│   ├── Data/                   # Data interfaces
│   │   ├── CartInterface.php
│   │   ├── CartItemInterface.php
│   │   ├── AddressInterface.php
│   │   └── TotalsInterface.php
│   ├── CartRepositoryInterface.php
│   ├── CartManagementInterface.php
│   ├── GuestCartManagementInterface.php
│   └── ...
├── Model/                      # Business logic (172 files)
│   ├── Quote.php               # Main quote model
│   ├── Quote/
│   │   ├── Item.php            # Quote item model
│   │   ├── Address.php         # Address model
│   │   ├── Payment.php         # Payment model
│   │   └── Address/
│   │       └── Total/          # Totals collectors
│   ├── GuestCart/              # Guest implementations
│   ├── Cart/                   # Cart helpers
│   ├── ValidationRules/        # Quote validators
│   └── ResourceModel/          # Database layer
├── Observer/                   # Event observers (5)
├── Plugin/                     # Interceptors (5)
├── Setup/                      # Schema setup
└── etc/
    ├── di.xml                  # 41 preferences
    ├── db_schema.xml           # 8 tables
    ├── webapi.xml              # 63 endpoints
    ├── events.xml              # Event subscriptions
    └── sales.xml               # Totals configuration