Overview

What This Plugin Adds

Shop is an Available, Schema-owning Capell package in the Capell Commerce product group. It ships as capell-app/shop and extends these surfaces: shared.

Shop is the Core-only Capell commerce engine and extension kernel. It provides typed, scoped capability contracts, deterministic ordering and provider-neutral lifecycle boundaries for later commerce surfaces. Runtime receipts and manifest declarations are reconciled through the Core extension contracts.

Later Admin, Storefront, API and provider packages can share one domain engine without importing each other’s UI or transport code. The kernel adds no Shop-only public render transport.

Status details:

Status: Available
Tier: premium
Bundle: commerce
Composer package: capell-app/shop
Namespace: Capell\Shop
Theme key: not applicable

Why It Matters

For developers: Typed capability contracts make context scope, extension ownership and duplicate-key failures explicit before catalogue or payment code lands. Core ordering and source-aware runtime receipts keep registration deterministic and auditable.

For teams: Teams can install the commerce engine for headless or physical-retail work without taking on Filament, Frontend or API packages.

Screens And Workflow

Docs gap: add docs/screenshots.json before promoting this package with visual workflow claims.

Admin index screen if the package has a Filament resource.
Create/edit screen if editors create records.
Settings/configuration screen when settings exist.
Frontend output when the package renders public pages.
Package detail or install intent screen when marketplace-owned.

Technical Shape

Service providers

Capell\Shop\Providers\ShopInstallServiceProvider
Capell\Shop\Providers\ShopServiceProvider

Migrations

packages/shop/database/migrations/2026_09_10_000001_create_shop_idempotency_keys_table.php
packages/shop/database/migrations/2026_09_10_000002_create_shop_outbox_events_table.php
packages/shop/database/migrations/2026_10_04_000001_remove_implicit_timestamp_updates_from_shop_shop_idempotency_keys.php
packages/shop/database/migrations/2026_10_04_000002_remove_implicit_timestamp_updates_from_shop_shop_outbox_events.php

Extension contracts

ShopAgentToolCapability
ShopCapability
ShopCapabilityManifestContribution
ShopCapabilityProvider
ShopCatalogueCapability
ShopExtension
ShopFulfilmentCapability
ShopIdempotency
ShopInventoryCapability
ShopLifecycleEvent
ShopMerchantOfRecordCapability
ShopOrderLifecycleCapability
ShopOutbox
ShopPaymentCapability
ShopPaymentPurposeCapability
ShopPipelineStage
ShopPricingCapability
ShopPromotionCapability
ShopRiskCapability
ShopSearchCapability
ShopShippingCapability
ShopSurfaceCapability
ShopTaxCapability

Actions

InstallShopPackageAction
ValidateShopCapabilityManifestAction

Data objects

ShopApplicabilityData
ShopCapabilityManifestContributionData
ShopCapabilityRegistrationData
ShopCapabilityScopeData
ShopContextData
ShopExtensionRegistrationData
ShopIdempotencyLeaseData
ShopIdempotencyReplayData
ShopIdempotencyRequestData
ShopLifecycleEventData
ShopManifestRuntimeReceiptData
ShopOutboxMessageData
ShopPipelineData

Manifest action API

install: Capell\Shop\Actions\InstallShopPackageAction

Manifest contributions

health-check: Capell\Shop\Health\ShopHealthCheck
migration: Capell\Shop\Manifest\ShopMigrationsContribution

Health checks

Capell\Shop\Health\ShopHealthCheck

Cache tags

shop

Data Model

Required tables: shop_idempotency_keys, shop_outbox_events.
Migration files: 2026_09_10_000001_create_shop_idempotency_keys_table.php, 2026_09_10_000002_create_shop_outbox_events_table.php, 2026_10_04_000001_remove_implicit_timestamp_updates_from_shop_shop_idempotency_keys.php, 2026_10_04_000002_remove_implicit_timestamp_updates_from_shop_shop_outbox_events.php.
Migration impact: run host migrations through the package install flow before opening package surfaces.
Deletion/retention behaviour: Docs gap: migrations and manifest contributions do not prove a cascade, pruning command, or timed retention policy.

Install Impact

Required packages: capell-app/core.
Admin navigation: no admin page or resource contribution is declared.
Admin/editor extensions: none declared.
Permissions: no package permission declarations or Shield gates detected; host access rules still apply.
Public routes: none declared.
Database changes: package migrations are declared.
Config: no package config files.
Settings: no package settings declared.
Queues or schedules: none declared.
Cache tags: shop.
Commands: none declared.

Common Pitfalls

Keep required Capell packages on compatible v4 releases: capell-app/core.
Run migrations before opening package resources or public routes.
Custom write integrations must preserve invalidation for shop cache tags.

Troubleshooting

Symptom	Likely cause	Check	Fix
Package surface is missing after install	Provider or manifest is not loaded	Confirm `capell.json`, package `composer.json`, and provider registration	Reinstall the package, refresh Composer autoload, and clear host caches
Admin screen or command fails on missing table	Package migrations have not run	Check the tables listed in `Data Model`	Run host migrations and rerun the focused package test

Quick Start

Install the package: composer require capell-app/shop.
Verify the package provider and manifest contributions are registered in the host app.