Docs
RU

Shop orders

uticms.shop.orders · verified 2026-07-14

Overview

Scope
Transactional commerce flow from basket conversion through stock and payment events

Key concepts

Basket Conversion
Transactional conversion of an active non-empty basket into an order with immutable order line snapshots.
Active Reservation
A temporary stock claim for an order, optionally scoped to a warehouse and expiring by configured TTL.
Reservation Commit
Stock deduction followed by a reservation status transition to committed.

Structure

  • Tables
    • Baskets
      • shop_baskets
      • shop_basket_items
    • Orders
      • shop_orders
      • shop_order_items
      • shop_order_history
    • Reservationsshop_stock_reservations
    • Payments
      • shop_payment_transactions
      • shop_receipts
  • Services
    • PlacementModules/Shop/Services/Order/OrderPlacementService.php
    • ReservationsModules/Shop/Services/Order/StockReservationService.php
    • Stock LifecycleModules/Shop/Services/Order/OrderStockLifecycle.php
    • EventsOrderLifecycleDispatcher

Facts

  • Shop orders store unique number, status, payment status, amounts, currency, customer/shipping data, integration fields, timestamps, and soft-deletion state. authoritative
  • Order items store a snapshot of type/entity, name, SKU, quantity, unit and total prices, currency, status, metadata, and external synchronization values. authoritative
  • OrderPlacementService rejects inactive or empty baskets and runs registered placement validators before its database transaction. authoritative
  • Placement locks offer-backed basket items with lockForUpdate before stock reservation work. authoritative
  • Placement creates order and item snapshots, optionally creates reservations, marks the basket converted, creates initial history, and dispatches the placed lifecycle event after commit. authoritative
  • StockReservationService derives active reservation expiry from shop.order.reservation_ttl_minutes; zero or negative TTL produces no expiry timestamp. authoritative
  • Cancellation releases active reservations; the expiry routine releases active expired reservations and also handles missing orders. authoritative
  • Commit locks active reservations, decrements offer quantity or warehouse stock, and marks reservations committed. authoritative
  • OrderStockLifecycle commits reservations when status changes to a configured commit status or payment_status changes to paid. authoritative

How-to guides

Place Order

  1. validate active non-empty basket and channel validators
  2. open transaction and lock offer-backed basket rows
  3. validate availability and create order/item snapshots
  4. create reservations when requested
  5. mark basket converted and persist order history
  6. dispatch placed event after transaction commit

Handle Order Status Change

  1. if status becomes cancelled, release active reservations
  2. if status or payment state reaches a commit condition, commit active reservations and deduct stock

Rules

Architectural rule

Do not recalculate historic order lines from mutable product or offer records; use the persisted order-item snapshot.

Architectural rule

Keep order creation, line snapshots, reservation creation, basket conversion, and initial history inside the placement transaction.

Examples

Placement Flow

ShopB2C CheckoutService -> Shop OrderPlacementService
validators tagged shop.order.placement.validators run before the transaction

modules/Shop/Services/Order/OrderPlacementService.php

Channel Validator Tag

$this->app->tag(B2cCheckoutPlacementValidator::class, 'shop.order.placement.validators');

modules/ShopB2C/Providers/ShopB2CServiceProvider.php