Promotion Benefit

First-Pass Node Dossier

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

What It Is

PromotionBenefit is the per-product discount configuration row used by per_product promotions. It links a promotion to a specific product and benefit type/value.

Parent hierarchy:

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

Primary implementation paths:

• packages/framework/src/Models/PromotionBenefit.php
• packages/framework/src/Services/Promotion/PromotionBenefitService.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Benefits
• packages/framework/src/Imports/Promotions/PromotionBenefitsSheetImport.php

What Users Can Do With It

Direct capabilities

Admin users can:

• add a product-specific benefit to a per_product promotion
• edit the benefit type and value
• delete the benefit
• import and export benefits through the promotions workbook

Indirect capabilities

Other workflows use promotion benefits:

• order-item calculators apply the per-product discount result to entitled items
• the promotion page only exposes benefit management when the parent promotion type is per_product

Where It Is Managed

Channel	Role	Notes
Admin promotion page	Direct	Benefits are managed through the nested benefits block and dialog
Excel import/export	Direct	Benefits are represented in per_product_configuration
Promotion calculators	Indirect	Benefits feed item-level discount calculations

Sources:

• packages/admin/resources/views/components/settings/promotion/page.blade.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Benefits/BenefitDialog.php
• packages/framework/src/Imports/Promotions/PromotionBenefitsSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionBenefitsSheet.php

Channel-Level Field Coverage

Admin benefit dialog

The packaged dialog exposes:

• target product
• type
• value

Additional UI behavior:

• percentages cannot exceed 100
• the dialog defaults to fixed_price when opening for a product

Source:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Benefits/BenefitDialog.php

Excel workbook

The per_product_configuration sheet supports:

• id
• promotion_id
• product_id
• benefit_type
• benefit_value
• action

Sources:

• packages/framework/src/Imports/Promotions/PromotionBenefitsSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionBenefitsSheet.php

Configuration And Data Model

Key model characteristics:

• promotion-owned
• product-owned
• benefit-type driven

Important fields:

Field	Purpose
promotion_id	owning promotion
product_id	product receiving the configured benefit
type	benefit calculation type
value	benefit amount or percentage

Important validation rules:

• benefit type must be a valid PromotionBenefitType
• value must be numeric and greater than 0
• percentage values in the admin dialog cannot exceed 100

Sources:

• packages/framework/src/Models/PromotionBenefit.php
• packages/framework/src/Services/Promotion/PromotionBenefitService.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Benefits/BenefitDialog.php

Relationships

PromotionBenefit directly relates to:

• promotion
• product

Source:

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

Rules And Downstream Effects

Important rules and effects:

• the benefit-management UI only appears when the parent promotion type is per_product
• changing benefits affects the order-item discount result for entitled items
• benefits are not the same as entitlements; entitlements decide which items qualify, then benefits define the item-level discount shape

Sources:

• packages/admin/resources/views/components/settings/promotion/page.blade.php
• packages/framework/src/Services/Promotion/Calculators/OrderItemsCalculator.php
• packages/framework/src/Services/Promotion/PromotionEligibilityService.php

Integrations And Automation

Excel

Benefits are directly supported in the promotions workbook under per_product_configuration.

Sources:

• packages/framework/src/Imports/Promotions/PromotionBenefitsSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionBenefitsSheet.php

Promotion calculation

Benefits feed the promotion calculation layer that produces item discount lines.

Source:

• packages/framework/src/Services/Promotion/Calculators/OrderItemsCalculator.php
• packages/framework/src/Services/Promotion/PromotionCalculatorService.php

Where It Appears To End Users

PromotionBenefit is not shopper-facing as a record, but it directly changes item-level discount outcomes that shoppers see in cart and checkout.

Source:

• packages/framework/src/Services/Promotion/Calculators/OrderItemsCalculator.php

Current Documentation Takeaways

• PromotionBenefit only becomes first-class when the promotion type is per_product.
• It is easy to confuse benefits with conditions; they solve different parts of the promotion pipeline.
• The workbook support makes benefits one of the clearer bulk-editable parts of the promotion system.

Open Questions

• This first pass did not identify a packaged standalone API for benefits outside the nested promotion workflow.
• Benefit behavior for fixed_uom_amount deserves a later deep dive tied to measurement-based pricing.