laravel-shop/.github/models.md

Models

The goal of this file is to not miss any important model traits, relationships, or details when working with the main models in the package.

Core Catalog

Product

• Central purchasable entity.
• Types: Simple, Variable, Grouped, External, Booking, Variation, Pool.
• Status: Draft, Published, Archived.
• Key Attributes: sku, slug, manage_stock, virtual, downloadable.
• Relationships: prices, stocks, categories, attributes, relations.

ProductPrice

• Defines the cost of a product.
• Types: One Time, Recurring (Subscriptions).
• Billing: Per Unit, Tiered.
• Key Attributes: currency, amount, compare_at_amount.
• Supports multi-currency and sale prices.

ProductStock

• Manages inventory levels.
• Types: Claimed, Return, Increase, Decrease.
• Status: In Stock, Out of Stock, Backorder.
• Key Attributes: quantity, sku (optional override).

ProductCategory

• Hierarchical organization for products.
• Relationships: parent, children, products.

ProductAttribute

• Custom properties (e.g., Color, Size, Material).
• Types: Text, Select, Boolean.
• Can be used for variations or information.

Shopping Experience

Cart

• Represents a shopping session.
• Status: Active, Abandoned, Converted, Expired.
• Key Attributes: currency, total, tax_total.
• Can belong to a User or be anonymous (Guest).

CartItem

• An item within a Cart.
• Links a Product (purchasable) and a specific ProductPrice.
• Key Attributes:
  • purchasable_id, purchasable_type: The product being purchased
  • product_id: For pool items, the allocated single item; otherwise null
  • price_id: The selected price model
  • currency: Currency from the selected price
  • quantity: Number of items
  • unit_amount: Base price per unit (per day for bookings)
  • price: Calculated price (unit_amount × days for bookings, same as unit_amount for simple)
  • subtotal: Total (price × quantity)
  • from, until: Booking date range (for booking products)

Order Management

Order

• Represents a finalized transaction.
• Status: Pending, Processing, On Hold, In Preparation, Ready for Pickup, Shipped, Delivered, Completed.
• Key Attributes: order_number, amount_total, amount_paid, billing_address, shipping_address.
• Links to User, Cart, and Purchases.

ProductPurchase

• An individual line item within an Order.
• Represents the immutable record of the product/price at the time of purchase.
• Status: Pending, Unpaid, Completed, Refunded, Cart, Failed.
• Tracks fulfillment status.

OrderNote

• Comments or logs attached to an order.
• Can be internal or customer-visible.

Payments & Identity

PaymentMethod

• Stored payment details (e.g., last 4 digits, brand).
• Tokenized reference to external provider.

PaymentProviderIdentity

• Links a local User to an external payment provider (e.g., Stripe Customer ID).