Promotion Condition

First-Pass Node Dossier

This page is an evidence-backed node dossier generated from the domain hierarchy and node questionnaire.

What It Is

PromotionCondition is the rule row that determines whether a promotion can apply and what it applies to. Each condition records a scope, a condition handler type, an operator, and a structured payload.

Parent hierarchy:

• Pricing & Promotions
• Promotions And Code Redemption
• Promotion Condition

Primary implementation paths:

• packages/framework/src/Models/PromotionCondition.php
• packages/framework/src/Services/Promotion/PromotionConditionService.php
• packages/framework/src/Services/Promotion/Conditions/PromotionConditionRegistry.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions

What Users Can Do With It

Direct capabilities

Admin users can:

• create requirement conditions
• create applies-to entitlement conditions
• edit existing conditions
• delete conditions

Indirect capabilities

Other workflows use conditions without exposing them outside the promotion page:

• eligibility validation checks prerequisites before allowing redemption
• entitlement checks decide which order items qualify
• promotion handlers can be extended through the condition registry

Where It Is Managed

Channel	Role	Notes
Admin promotion page	Direct	Conditions are created and managed from the conditions block
Condition registry	Direct system-owned	Available condition classes and scopes are registered here
Promotion eligibility service	Indirect	Runtime cart validation evaluates stored conditions
Excel import/export	Not confirmed	This sprint did not find a packaged worksheet for conditions

Sources:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions/Block.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions/EditDialog.php
• packages/framework/src/Services/Promotion/Conditions/PromotionConditionRegistry.php
• packages/framework/src/Services/Promotion/PromotionEligibilityService.php

Channel-Level Field Coverage

Admin create and edit dialogs

The packaged dialog takes parent promotion context plus these user-facing inputs:

• conditionScope
• conditionType
• operator
• payload

The parent promotionId is passed into the Livewire component as context rather than entered directly by the operator.

Supported packaged form components in this sprint include:

• customer group
• subtotal price
• shipping address
• product type
• product category
• product manufacturer / brand
• minimum quantity

Sources:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions/CreateDialog.php
• packages/admin/resources/views/components/settings/promotion/conditions/forms

Model fields

The stored condition fields are:

• promotion_id
• scope
• condition_type
• operator
• payload

Source:

• packages/framework/src/Models/PromotionCondition.php

Configuration And Data Model

Key model characteristics:

• promotion-owned
• handler-driven
• scope-aware
• payload-based

Important field groups:

Field Group	Purpose
ownership	promotion_id
rule semantics	scope, condition_type, operator
structured data	payload

Important validation rules:

• scope must be a valid PromotionConditionScope
• condition type must be registered for the selected scope
• payload must pass the selected handler's validation rules

Sources:

• packages/framework/src/Models/PromotionCondition.php
• packages/framework/src/Services/Promotion/PromotionConditionService.php
• packages/framework/src/Enums/Promotion/PromotionConditionScope.php

Relationships

PromotionCondition directly relates to:

• promotion

Its real business linkage is to the registered condition handler class referenced in condition_type.

Sources:

• packages/framework/src/Models/PromotionCondition.php
• packages/framework/src/Services/Promotion/Conditions/PromotionConditionRegistry.php

Rules And Downstream Effects

Important rules and effects:

• pre_requisites are evaluated against the order before a code can be applied
• entitlements are evaluated against order items to determine which lines can receive the discount
• the admin UI hides condition handlers that are blacklisted for the current promotion target
• invalid handler classes or invalid payloads fail validation before persistence

Sources:

• packages/framework/src/Services/Promotion/PromotionConditionService.php
• packages/framework/src/Services/Promotion/PromotionEligibilityService.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Conditions/CreateDialog.php

Integrations And Automation

Registry and config

Condition availability is registry-driven and can be extended through configured condition classes.

Sources:

• packages/framework/src/Services/Promotion/Conditions/PromotionConditionRegistry.php
• packages/framework/config/promotions.php

Runtime evaluation

Conditions are consumed by the promotion eligibility pipeline at redemption time.

Source:

• packages/framework/src/Services/Promotion/PromotionEligibilityService.php

Where It Appears To End Users

PromotionCondition is not a shopper-facing concept.

It appears for operators through the promotion page's conditions block, and for shoppers indirectly when a code is accepted or rejected.

Sources:

• packages/admin/resources/views/components/settings/promotion/conditions/block.blade.php
• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php

Current Documentation Takeaways

• Conditions are the main reason a valid-looking code may still fail at checkout.
• The packaged admin treats prerequisites and entitlements as separate workflows because they answer different business questions.
• Condition management is currently UI-first. This sprint did not find a packaged workbook or standalone API for it.

Open Questions

• This first pass did not identify a packaged import/export surface for conditions.
• The exact set of custom host-app condition classes, if any, was not explored beyond the default registry.