Skip to content

Commerce Engine

Status: Draft for review

Purpose

Own sellable/reservable offerings and the runtime mechanics of availability, inventory, resources, pricing, quotes, carts/orders, bookings/reservations, coupons, cancellation and fulfillment state.

Owns

  • Offerings and offering status
  • Resource instances/pools and schedules
  • Availability/inventory state and overrides
  • Price rules and authoritative price quotes
  • Add-ons/extras
  • Carts where used
  • Enquiry/request/quote/booking/reservation transaction state
  • Orders and cancellation/refund requests (financial execution delegated to Finance)
  • Coupons/promotions as commerce adjustments

Non-goals

It does not own tenant subscription billing, page composition, advertising accounts or raw payment-gateway credentials.

API contract — functional surface

These are contract-level resources and operations, not final controller/file names.

Method Route Primary actor Contract intent
GET /api/public/v1/offerings Visitor Search/list published offerings scoped by resolved site/tenant.
GET /api/public/v1/offerings/{idOrSlug} Visitor Read public offering detail.
POST /api/public/v1/availability/query Visitor Calculate availability/capacity for requested criteria.
POST /api/public/v1/pricing/quote Visitor Return authoritative, expiring price quote.
POST /api/public/v1/enquiries Visitor/Customer Create enquiry-only lead transaction.
POST /api/public/v1/booking-requests Visitor/Customer Create request-to-book.
POST /api/public/v1/quotes/requests Visitor/Customer Start quote-required workflow.
POST /api/public/v1/bookings Customer/Guest Checkout Create instant booking against availability and price quote.
GET /api/tenant/v1/bookings Tenant Staff Search operational bookings.
PATCH /api/tenant/v1/bookings/{id}/status Authorized Staff Apply valid booking state transition.
POST /api/tenant/v1/offerings Business Manager Create offering conforming to enabled schema.
PUT /api/tenant/v1/offerings/{id}/availability Business Manager Manage availability rules/overrides.
PUT /api/tenant/v1/offerings/{id}/pricing Business Manager Manage pricing rules.

All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.

Events

  • offering.published
  • availability.changed
  • price_rule.changed
  • lead.created
  • quote.issued
  • quote.accepted
  • booking.created
  • booking.confirmed
  • booking.cancelled
  • order.created

Roles & responsibility matrix

Legend: A accountable, R responsible, C consulted, I informed, — none.

Capability Platform Admin Tenant Owner Tenant Admin Specialist/Manager Customer/Visitor
Commerce policy/platform rules C A R R I
Offering/resource maintenance — A C R I
Availability/pricing — A C R I
Book/request/enquire — I I C R
Override/cancel booking I A R R C

Dependencies

  • Capability Engine for schemas/model eligibility
  • Platform Engine for entitlement and tenant scope
  • CRM Engine for customer/lead identity and communications
  • Finance Engine for payment/refund execution
  • Operations Engine for jobs/audit

Internationalization Contract

  • Offering/package/add-on/policy display text is translatable; IDs, prices, quantities and workflow states are locale-neutral.
  • Pricing calculations return canonical money values; locale formatting is presentation-only.
  • Availability, departures, appointments and similar schedules retain authoritative location/resource IANA timezone semantics.
  • Booking/customer-facing errors use stable codes with locale-aware presentation.

Security / isolation requirements

  • Booking creation is idempotent and rechecks authoritative availability.
  • Price quotes are immutable snapshots with expiry/version identity.
  • Inventory updates are concurrency-safe.
  • Tenant scope applies to offerings/resources/orders/bookings.

Acceptance criteria

  • All legacy instant/enquiry/external modes have mapped transaction behavior.
  • Yacht charter, appointments, nightly accommodation, vehicle rentals, tee times and group excursions can be represented without separate commerce engines.
  • Availability conflicts cannot double-allocate protected resources.
  • Cancellation policy and financial refund responsibilities are separated cleanly.