Promotion

First-Pass Node Dossier

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

What It Is

Promotion is the top-level campaign record for discount logic in Pyle. It defines the promotion's title, target, type, value, date range, combinability, and active state, and it owns codes, conditions, benefits, and redemptions.

Parent hierarchy:

• Pricing & Promotions
• Promotions And Code Redemption
• Promotion

Primary implementation paths:

• packages/framework/src/Models/Promotion.php
• packages/framework/src/Services/Promotion/PromotionService.php
• packages/admin/src/Livewire/Admin/Settings/Promotions
• packages/admin/src/Livewire/Admin/Settings/Promotion
• packages/framework/src/Services/Promotion/PromotionCalculatorService.php

What Users Can Do With It

Direct capabilities

Admin users can:

• create a promotion from Settings > Promotions
• edit core promotion details on the promotion page
• activate or deactivate a promotion
• delete a promotion when it has not been used
• export and import promotions through Excel

Indirect capabilities

Other workflows use the promotion record:

• codes attach redemption entry points to the promotion
• conditions control eligibility and entitlements
• benefits define per-product discount behavior for per_product promotions
• cart recalculation applies the promotion after code redemption

Where It Is Managed

Channel	Role	Notes
Admin promotions list	Direct	Search, filter, create, and open promotions
Admin promotion page	Direct	Basic information, codes, benefits, conditions, and sidebar actions
Excel import/export	Direct	Promotions, codes, and per-product benefits are workbook-backed
Storefront cart	Indirect	Shoppers never manage promotions directly, but promotions are applied through codes
Feature flag	Direct system-owned	Promotions UI and behavior are gated by PromotionsFeature

Sources:

• packages/admin/routes/web.php
• packages/admin/src/Livewire/Admin/Settings/Promotions/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Page.php
• packages/framework/src/Imports/Promotions/PromotionsImport.php
• packages/framework/src/Exports/Promotions/PromotionsExport.php
• packages/framework/src/Features/PromotionsFeature.php

Channel-Level Field Coverage

Admin create dialog

The packaged create flow requires:

• title
• target

Source:

• packages/admin/src/Livewire/Admin/Settings/Promotions/CreateDialog.php

Admin promotion page

The basic information block edits:

• title
• type
• target
• value
• range / starts_at / ends_at
• shipping_cutoff_at
• combinable
• active

Sources:

• packages/admin/src/Livewire/Admin/Forms/PromotionForm.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/BasicInformationBlock.php

Excel workbook

The promotions workbook includes:

• promotions
• promotion_codes
• per_product_configuration
• documentation

Sources:

• packages/framework/src/Exports/Promotions/PromotionsExport.php
• packages/framework/src/Imports/Promotions/PromotionsImport.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• date-window aware
• target- and type-driven
• campaign-owned parent for codes, conditions, benefits, and redemptions

Important field groups:

Field Group	Purpose
campaign identity	title
discount definition	type, target, value
scheduling	starts_at, ends_at, shipping_cutoff_at
operational state	combinable, active

Important validation and lifecycle rules:

• percentage promotions cannot exceed 100
• the selected target must be enabled in config/promotions.php
• promotions with existing redemptions cannot be deleted

Sources:

• packages/framework/src/Models/Promotion.php
• packages/framework/src/Services/Promotion/PromotionService.php
• packages/framework/config/promotions.php
• packages/admin/src/Livewire/Admin/Forms/PromotionForm.php

Relationships

Promotion directly relates to:

• promotionCodes
• promotionConditions
• benefits
• promotionRedemptions

Source:

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

Rules And Downstream Effects

Important rules and effects:

• activeAndValid requires a valid date window and active = true
• per_product promotions activate the benefit-management block on the promotion page
• code redemption eventually routes into promotion eligibility and calculator services
• shipping_cutoff_at can reject an otherwise-valid code when the order contains shipping lines with pickup dates after the cutoff
• deleting a promotion cascades into promotion-code cleanup through promotion-deletion listeners

Sources:

• packages/framework/src/Models/Promotion.php
• packages/admin/resources/views/components/settings/promotion/page.blade.php
• packages/framework/src/Services/Promotion/PromotionEligibilityService.php
• packages/framework/src/Services/Promotion/PromotionCalculatorService.php
• packages/framework/src/Listeners/DeletePromotionRedemptionsListener.php

Integrations And Automation

Excel

Promotions are fully represented in the packaged import/export workflow, including documentation for valid enum values.

Sources:

• packages/admin/src/Livewire/Admin/Tools/Excel/ExportDialog/PromotionsExport.php
• packages/admin/src/Livewire/Admin/Tools/Excel/ImportDialog/PromotionImport.php
• packages/framework/src/Exports/Promotions/Sheets/DocumentationSheet.php

Cart application

Promotions are applied indirectly through code redemption and order recalculation services.

Sources:

• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php
• packages/framework/src/Services/Promotion/PromotionRedemptionService.php
• packages/framework/src/Services/Promotion/PromotionCalculatorService.php

Where It Appears To End Users

Promotion is first-class for admin users, but indirect for shoppers.

It appears through:

• the promotions list and promotion detail screens in admin
• cart discount application and resulting order discount lines

Sources:

• packages/admin/src/Livewire/Admin/Settings/Promotions/Table.php
• packages/admin/resources/views/components/settings/promotion/page.blade.php
• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php

Current Documentation Takeaways

• Promotion is the campaign root. Codes, conditions, and benefits are subordinate configuration layers.
• The packaged admin UI for promotions is real and first-class, unlike the direct product-offer management experience found in this sprint.
• Promotion behavior is operational, not cosmetic. Scheduling, combinability, and target selection directly affect checkout outcomes.

Open Questions

• This first pass did not identify a packaged public or admin API for promotions comparable to the product-offer API.
• Promotion conditions are configurable in admin UI, but not represented in the packaged Excel workbook.
• shipping_cutoff_at validation is inconsistent between the packaged admin form (after_or_equal promotion end) and the promotion service (after_or_equal promotion start), so the exact authoring constraint needs reconciliation.