Repository navigation
Releases
v1.3.0
Payment gateways that share one provider webhook endpoint can settle their
siblings' checkouts, providers can record refunds and payment failures they
made on their own, and API storefronts can pass gateway payment options when
they open a payment session. Marketing notifications now need the
customer's marketing consent.
Added
Contracts\SharesWebhookEndpoint(optional, on aPaymentGateway):webhookGatewayKeys()lists the gateway keys whose sessions a gateway's webhooks report on, so one provider endpoint (such aswebhooks/paypal) can settle checkouts made through its sibling gateways (paypal-card,paypal-apple-pay, …). Declared keys that aren't registered inPaymentGatewayRegistryare dropped, and the gateway's own key is always included (#207).PaymentReconciler::webhookGatewayKeys( $gatewayKey ): the key set a reported outcome may settle (#207).RefundService::recordProviderRefund( $order, $amount, $gatewayReference, $reason, $issuedRefundId )records a refund the payment provider already made, such as a dashboard refund reported by webhook, without calling the gateway. It writes asucceededamount-only refund, updates the order's refunded total andpayment_status, writes anorder.refundedtimeline entry withsource: provider, and firesap.ecommerce.payment.refunded/ap.ecommerce.order.refundedand thePaymentRefunded/OrderRefundedevents. It is idempotent ongateway_reference, and on$issuedRefundId(the engine refund id the provider echoes back), which also matches a refund the store issued that is still pending (#209). A refund the store issued that was markedfailed(the gateway call errored or timed out) is settled when the provider reports it completed and echoes back its id: the same guards apply, its restock lines are restocked, and the order's totals,payment_statusand timeline (settled_failed_refund: true) are updated as for a refund that succeeded the first time. When the provider's amount differs, arefund.amount_mismatchentry is written andRefundNotAllowedExceptionis thrown.PaymentGatewayContractTestchecks that a gateway implementingSharesWebhookEndpointlists its own key and that every key it lists is registered; the check is skipped for other gateways (#207).Contracts\AcceptsPaymentOptions(optional, on aPaymentGateway):paymentOptionRules( $cart )andpaymentOptionsChanged( $cart, $session, $options )let API storefronts send gateway-specific choices, such as saving a payment method or paying with a saved one, when they create a payment session.POST checkout/{cart}/sessionand the GraphQLcreatePaymentSessionmutation acceptpayment_options.CheckoutService::createPaymentSession()validates them against the gateway's rules, refuses unknown keys and invalid values (payment-options-invalid, 422), passes the validated keys to the gateway as$context['payment_options'], and reuses the cart's session only while the gateway says it matches them.PaymentGatewayContractTestchecks the rules of gateways that implement the contract (#211).PaymentOrchestrator::recordProviderPaymentFailure( $order, $captureReference, $code, $message )records that the provider failed a payment the store already counted as paid, such as a pending capture it later denied. Apaidorder with nothing refunded moves topayment_status = failed,meta.payment.capture_failurerecords the reference, code and time, apayment.capture_failedtimeline entry is written withsource: provider, andap.ecommerce.payment.failedandPaymentFailedfire after commit (a throwing listener is reported, not rethrown). It does nothing for a refunded order or a different capture reference, and leaves the order's status, stock and deliverables to store policy.Refund::settleFailedAsSucceeded( $gatewayReference ): the one change a failed refund allows, used when the provider reports it completed.NotificationPreferenceService::withdrawMarketing( $customer )andNotificationPreferenceService::CATEGORY_MARKETING.PaymentGatewayContractTest::paymentOptionsCart(): satellites whose gateway only returns payment-option rules for some carts (a signed-in owner's, say) override it so their rules are checked.
Changed
PaymentReconciler(webhooks throughJobs\ReconcilePaymentSession, andecommerce:reconcile-payments) matches carts and pending orders on that key set. When a reference matches more than one checkout, the most recently updated one is settled and a warning is logged to theecommercechannel.PaymentReconcilertakes an optionalPaymentGatewayRegistryconstructor argument. Gateways without the contract behave as before (#207).
Fixed
- Marketing notifications need the customer's marketing consent (#194). A stored preference can turn marketing off but no longer on without
accepts_marketing;NotificationPreferenceService::update()refuses to turn marketing on without consent (PATCH me/notification-preferencesanswers 422), and withdrawing consent (throughPATCH meor the adminPATCH customers/{id}) stores marketing off on every channel.
v1.2.0
Kanban boards keep a manual card order, read their cards through one
filterable query, broadcast every change as an id-only board event, take
per-instance card widget settings, and edit columns through one service, so
the board satellites need no kanban logic of their own.
Added
- Manual card order on kanban boards (#198).
ecommerce_order_board_assignmentsgains aposition(existing cards are numbered in the order they reached their column).KanbanBoardService::move()takes an optionalKanban\KanbanCardPlacement(top(),bottom(),before( $orderId ),after( $orderId )); a same-column move with a placement reorders the card without a status change, WIP check, or automations, and firesap.ecommerce.kanban.cardReorderedandEvents\KanbanCardReordered.ap.ecommerce.kanban.cardMovingreceives the placement asplacementand may change it. artisanpack.ecommerce.kanban.new_card_position(bottom/top, envECOMMERCE_KANBAN_NEW_CARD_POSITION): where cards that join a board land in their column (#198).- REST
POST kanban/cards/{order}/moveacceptsposition(top/bottom),before_order_id, orafter_order_id; card resources exposeposition(#198). Kanban\KanbanCardQuery(itsfilter()andcolumn()return a narrowed copy, so one query can be reused) andKanban\KanbanCardFilters: a board's cards filtered by search (order number, email, billing / shipping / customer name), customer, tags (any / all), products (and their variants), placed date range, stale cards, and payment and fulfillment status, in manual order, cursor-paginated, with filtered and total counts per column. Satellites add filters throughap.ecommerce.kanban.cardQuery(#199).Kanban\KanbanCardTags::forBoard(): the distinct tags on a board's cards, for a filter bar's options (#199).Order::kanbanCardRelations()(filterable throughap.ecommerce.kanban.cardRelations): what card widgets read, eager-loaded with the cards (#199).- REST
GET kanban/boards/{board}/cardsaccepts the card filters asfilter[...];GET kanban/boards/{board}addsfiltered_card_countto each column when they are passed (#199). - Board events on
private-ecommerce.kanban.board.{board}(#200): withkanban.broadcaston, cards added, removed, moved, reordered, and updated, board and column configuration changes, and automations that fired or failed are broadcast askanbanBoardEvent(Broadcasting\KanbanBoardBroadcast) with an id-only payload:{ type, board_id, order_id, column_id, from_column_id, to_column_id, position, actor_user_id, occurred_at }. Broadcasts go out after commit onkanban.broadcast_connection/kanban.broadcast_queue(envECOMMERCE_KANBAN_BROADCAST_CONNECTION/_QUEUE); a broadcaster failure is logged and never fails the write. The existingkanbanCardMovedbroadcast stays. Events\KanbanBoardConfigChangedandEvents\KanbanAutomationFailed(#200).Kanban\KanbanCardRefresher::refresh( $order, ?$widgetKey )broadcastscard-updatedto each active board an order is on, after commit and debounced per request (#201). The core calls it when an order's payment or fulfillment status, totals, ormeta.tagschange, on order edits, and on new shipments; satellites call it for their own widgets.- Per-instance card widget config (#202): column
card_widgetsand boardsettings.card_widgetsaccept{ key, config }entries next to plain keys (Kanban\KanbanWidgetList), validated against the widget'sconfigSchema()with undeclared keys rejected (lists hold at most 50 entries and each config at most 50 settings). Widgets opt in withContracts\ConfigurableKanbanCardWidget::renderWithConfig();AbstractKanbanCardWidgetimplements it and exposes$this->config(). Config merges as schema defaults →kanban_card_widgets.default_config→ instance config, and a storedkanban_card_widgets.labelreplaces the widget's label.days-in-columntakesstale_after_daysandtagstakesmax_tags. Services\KanbanCardWidgetService: a board's default widget list and the store-wide widget overrides; RESTPUT/DELETE kanban/widgets/{key}; a change tells every active board to refresh and firesap.ecommerce.kanban.widgetOverrideSaved/widgetOverrideReset(#202). An override stores a label only when one is given (an empty label clears it), so a config-only override keeps the widget's own translated label;ecommerce_kanban_card_widgets.labelbecomes nullable, and widget resources addlabel_override(null when the widget's own label is used).KanbanCardRenderer::widgetEntries(),widgetSource()(column/board/default), andconfig().Services\KanbanColumnServicewithcreate(),update(),reorder(), anddelete()(#203): the column rules in one place, a bulk reorder in one transaction (RESTPUT kanban/boards/{board}/columns/order), deleting a column with cards refused withExceptions\KanbanColumnNotEmptyException(carrying the card count) or its cards moved to a named column first (RESTDELETE kanban/columns/{column}takesmove_cards_to, which also needskanbanCard.move; at mostKanbanColumnService::MAX_CARDS_MOVED_ON_DELETEcards), andap.ecommerce.kanban.column{Created,Updated,Reordered,Deleted}actions.
Changed
- REST
GET kanban/boards/{board}/cardslists cards in their manual order (position, then when they joined the board) by default; passsort=assigned_atfor the old order (#198). KanbanBoardServiceandKanbanRoutingServicetake aKanban\KanbanCardPositionsconstructor argument, andKanbanBoardService::filteredTarget()returns the target column and placement as a pair. Card moves now lock the source and target columns before the card (#198).KanbanCardMoved,KanbanCardReordered,KanbanBoardAssignmentAdded, andKanbanBoardAssignmentRemovedcarry an optionalactorUserId(#200).- The REST column endpoints write through
KanbanColumnService; their behavior is unchanged (#203). Column resources keepcard_widgetsas a list of widget keys and addcard_widget_entries({ key, config }pairs, GraphQL[JSON!]!) (#202). KanbanCardRendereris bound scoped, so widget overrides load once per request (#202).- A broadcaster failure while broadcasting
kanbanCardMovedis logged instead of failing the move (#200).
v1.1.0
Storefront listings, carts, and variable product pages now price and stock
products in a fixed number of queries, the OpenAPI spec takes its version
from the release tag, and the engine installs on MySQL.
Added
Product::withDisplayData()scope andProduct::displayRelations(): eager-load what a display price and stock state need (prices, stock rows, variants with theirs) (#195).Tax\TaxRateCandidates(scoped): active tax rates are read once per request per tax class and country, and re-read after aTaxRateis saved or deleted (#195).StockLevels::itemFor(),available(), andsellable()take an optional$preferLoadedflag to read a loadedinventoryItemsrelation. OnlyStockStatususes it; reservations, checkout, and refunds always read fresh rows (#195).ecommerce:generate-openapi --spec-version=sets the spec'sinfo.version(a leadingvis dropped; anything that isn't a semantic version is refused). The release workflow passes the tag (#189).OpenApiGenerator::generate()takes an optional version, andOpenApiGenerator::normalizeVersion()reads a version or tag.
Changed
ProductPriceResolver,PriceDisplayResolver,StockStatus, and product-type variant lookup use relations the caller already loaded instead of querying per product or variant;VariantResolver::matrix()loads variant prices and stock once. Nothing changes for callers that load nothing (#195).- Without
--spec-version,info.versioncomes fromcomposer.json, then the installed engine version. It falls back to0.0.0-dev(OpenApiGenerator::FALLBACK_VERSION), not a hard-coded release number that had to be bumped by hand each release.
Fixed
- MySQL install: the
product_variant_idforeign key onecommerce_product_variant_option_valuesis namedecommerce_pvov_variant_fk. Laravel's default name was 66 characters, past MySQL's 64-character limit, somigratefailed on MySQL. Existing SQLite and Postgres installs are unaffected. A test now compiles every migration as MySQL and fails on any identifier over 64 characters (#191).
v1.0.1
A patch release for satellite verification: signed reports now reach a
release under a name GitHub keeps.
Fixed
- Satellite verification report asset name: GitHub renames a release asset whose name starts with a dot, so a report attached as
.ecommerce-verify-report.jsonwas published asdefault.ecommerce-verify-report.json(#186).- The reusable
verify-satelliteworkflow now addsecommerce-verify-report.jsonto theecommerce-verify-signatureartifact. It's the same signed bytes, and attaching it keeps its name. - The dotfile stays in the artifact for release steps written against v1.0.0.
- The workflow stub attaches
ecommerce-verify-report.jsonand pinsverify-satellite.yml@v1.0.1.
- The reusable
- The workflow stub pins
softprops/action-gh-releaseto a full commit SHA, since its release step runs withcontents: write. - The OpenAPI spec reports the release's version (
info.version).
Changed
- Satellites page (
docs/satellites.md):- The contract-verified rule looks for
ecommerce-verify-report.json. It still accepts thedefault.ecommerce-verify-report.jsonasset that releases made with the v1.0.0 stub carry. - Publishes the ArtisanPack UI organization's signing key.
- Lists
artisanpack-ui/ecommerce-admin-livewireas contract-verified.
- The contract-verified rule looks for
- Satellite verification guide (
docs/satellite-verification.md): the CI example uses the new asset name and engine tag, and shows how to check a published release's signature.
v1.0.0
The first stable release of the headless commerce engine. Storefront, admin,
and integration packages plug in as satellites through its contracts,
registries, and hooks.
Added
- Catalog:
- simple, digital, variable, grouped, and bundled product types through
ProductTypeRegistry; - variants, attributes, scheduled per-currency prices with compare-at prices, images, a category tree, and tags;
ProductServiceas the one write path.
- simple, digital, variable, grouped, and bundled product types through
- Catalog reads for storefronts:
CatalogQuerywith filters, sorts, and facets;- display prices with and without tax (
PriceDisplayResolver); - variant matching and the variant matrix (
VariantResolver); - read-only stock status;
- related products, upsells, and cross-sells;
- add-to-cart field descriptions for grouped and bundled products (
ProvidesStorefrontOptions); - the
ap.ecommerce.product.viewedhook.
- Search:
- the
SearchProvidercontract with facets and suggestions; - a default provider built on Laravel Scout and the catalog query;
- the
SearchIndexercontract; - a richer search document for dedicated engines.
- the
- Carts:
- server-side pricing;
- options validation, stock checks, and a line cap;
- expiry;
- coupons;
- shipping quotes and rate selection;
- tax-inclusive and tax-exclusive totals;
- free-item and free-shipping promotions;
- the shopper's current cart, with the guest cart merged on login;
- abandoned-cart flagging (
CartAbandoned) and pruning.
- Checkout: the engine provides checkout services and APIs, and storefronts build the flow and UI.
CheckoutService(email, addresses, shipping method, payment gateway, payment session, finalize) and stock reservations;OrderPlacementService(tax at placement, per-line allocation, coupon usage limits);- two-phase finalize and resume in
PaymentOrchestrator; - reconciliation of payment outcomes from webhooks and
ecommerce:reconcile-payments.
- Payments:
- the
PaymentGatewaycontract and registry; - Stripe Payment Intents (SAQ-A) with automatic or manual capture;
RendersClientPaymentclient configuration for embedded or redirect flows;- fraud screening with chainable providers and Stripe Radar.
- the
- Pricing and promotions:
- automatic and coupon promotions;
- conditions:
min-subtotal,min-quantity,cart-contains-product,cart-contains-product-type,cart-contains-category,cart-contains-tag,customer-in-group,customer-first-order,customer-lifetime-value-over,day-of-week,date-range,currency-is; - actions:
percent-off-cart,fixed-off-cart,percent-off-product,fixed-off-product,free-shipping,buy-x-get-y,add-free-item,tiered-discount; - config schemas for admin forms;
- multi-currency prices with FX providers (
config,frankfurter), last-known-good rates, andecommerce:refresh-fx-rates.
- Tax and shipping:
- the
TaxProvidercontract with the manual tax-rate provider (postal patterns, ZIP+4, ranges, compound rates); - shipping zones, method types, and rate providers;
- shipments with tracking;
- the label provider contract;
- local pickup with QR handoff.
- the
- Orders:
- a two-tier status machine with sub-statuses and a consistency audit;
- edits with tax recalculation and rollback;
- cancellation;
- full and partial refunds with restocking;
- notes, timeline, and fulfillment allocation.
- Customers:
- guest and account customers, with verified-email linking;
- addresses, notes, and lifetime stats;
- guest-order claims;
- GDPR delete-and-anonymize.
- Customer self-service (
me/*):- profile and language;
- addresses, orders, and claims;
- digital downloads and license keys;
- notification preferences;
- an account menu through
AccountMenuRegistry.
- Guest order access: guest order lookup by email and order number, and signed order links in guest confirmations.
- Reviews:
- moderation through
ReviewModerator, and rating aggregates with a histogram; - eligibility rules (
reviews.require_purchase,reviews.allow_multiple), with automatic verified-purchase detection; - review photos through media-library.
- moderation through
- Digital delivery and licenses:
- download tokens with limits and expiry, streaming, and owner downloads;
- digital file versions and archiving;
- license keys stored encrypted and hashed, with activation limits, validation, deactivation, and revocation.
- Notifications:
- a catalog of order, shipping, review, digital, license, and stock notifications;
- store-editable copy in a Twig sandbox;
- customer preferences;
- copy in the recipient's language;
- a plain-text part and one-click unsubscribe.
- Kanban: order boards with auto-routing, automations and triggers, card widgets, and broadcasting.
- Outbound webhooks:
- signed deliveries for domain events, with retries and backoff;
- subscription auto-disable;
- delivery history and replay, including replay of parked deliveries.
- Domain events:
OrderPlaced,CartCompleted,CartAbandoned,CouponRedeemed,PromotionApplied;ShipmentCreated,ShipmentDelivered,OrderFulfilled;CustomerRegistered,CustomerUpdated;ProductStockLow,ProductOutOfStock;LicenseDeactivated;- plus the payment, refund, review, license, and kanban events.
- REST API (
/api/ecommerce/v1):- storefront, shopper, and admin endpoints;
- cursor and page pagination with allow-listed filters, sorts, and includes;
- idempotency keys and named rate-limit policies;
- problem+json errors;
- catalog caching with ETags.
- GraphQL API: an optional
ecommerceschema on rebing/graphql-laravel, with depth, complexity, and batch limits and subscriptions. - OpenAPI 3.1 generation (
ecommerce:generate-openapi), with query parameters and response schemas for every operation. - API authentication:
- Sanctum tokens with per-resource scopes;
- signed service-to-service requests;
- default-deny abilities with resource-level overrides;
- cms-framework permissions, the shop-manager role, and
ecommerce:sync-permissions.
- Store administration:
- persisted store settings;
- reports (sales summary, sales, top products, line items, tax collected, revenue by category, inventory, inventory levels, low stock) in the store time zone and net of refunds;
- an activity log;
- admin menu and notification channel registries.
- Satellites:
- contracts and registries for product types, gateways, tax, shipping, labels, FX rates, fraud, promotions, kanban, notifications, search, reviews, cart storage, and order numbers;
- contract test suites shipped in the package;
ecommerce:verify-satellitewith signed reports;- satellite install, uninstall, reinstall, and orphan audits.
- Localization:
en,es,fr, anddecatalogues, with regional-locale fallback;- locale-aware money formatting;
Accept-Languagenegotiation;- a translation linter for engine and satellite code.
- Operations:
- a configurable single-server schedule (
schedule.*); - ledger retention with
ecommerce:prune-ledgers; - structured JSON logging with request ids carried into queued jobs;
- optional Sentry context;
- a demo store seeder;
- a PCI column lint.
- a configurable single-server schedule (
- WordPress-style hooks across the cart, order, pricing, tax, shipping, payment, product, customer, and API layers.
- The
Ecommercefacade andecommerce()helper, withcart(),checkout(),orders(),payments(),catalog(),customers(), andinventory()accessors. - Support for Laravel 12 and 13 on PHP 8.2 and later.
Changed
- Every engine table is prefixed with
ecommerce_. Hosts that publish the migrations can opt out of the engine's own withEcommerce::ignoreMigrations(). stripe/stripe-phpandrebing/graphql-laravelare optional (suggested) dependencies. The engine boots and serves REST without them.NotificationTemplate::defaultSubject()anddefaultBody()take an optional locale, so catalog copy is translated when it is sent.- Validation errors report the failed rule's name as the error
code, and every API error isapplication/problem+json.
Security
- Shopper-facing data: API responses never expose staff-internal fields such as fraud verdicts, refund references, or storage paths to shoppers.
- Token scopes: refunds, cancellations, customer deletion, and settings writes each need a dedicated token scope.
- Inbound webhooks:
- unknown providers and oversized bodies are refused without being stored;
- unverified requests keep only a hash, the size, and the first kilobyte;
- every request counts against a per-IP limit, and only verified deliveries count against the provider's allowance.
- Outbound webhooks resolve, pin, and re-check every IP address to block SSRF into private networks.
- Idempotency and rate limits:
- money-moving GraphQL mutations need an
Idempotency-Key; - guest idempotency keys must be long random strings;
- guest order lookups lock out after repeated failures.
- money-moving GraphQL mutations need an
- Stored secrets: license keys are stored encrypted and matched by hash. Inbound webhook payloads are scrubbed when a customer is anonymized.
- Signed service requests are checked against a replay cache (
api.signature_cache_store); the engine warns in production when that store isn't shared between servers. - Demo seeder:
ecommerce:seed-demo --freshcan't empty a production store without an explicit confirmation flag.