Promotion Code

First-Pass Node Dossier

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

What It Is

PromotionCode is the shopper-entered or operator-managed code that redeems a promotion. It links a promotion campaign to usage limits and to the actual redemption records created on orders.

Parent hierarchy:

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

Primary implementation paths:

• packages/framework/src/Models/PromotionCode.php
• packages/framework/src/Services/Promotion/PromotionCodeService.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes
• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php

What Users Can Do With It

Direct capabilities

Admin users can:

• create a single code for a promotion
• bulk-generate codes with a prefix
• edit an existing code and its limits
• delete a code
• import and export codes through the promotions workbook

Indirect capabilities

Other workflows use promotion codes without editing them:

• storefront cart users apply the code during checkout
• redemption services validate usage limits, eligibility, and combinability
• redemption history persists after code use

Where It Is Managed

Channel	Role	Notes
Admin promotion page	Direct	Codes are created and maintained from the nested promotion codes block
Storefront cart	Direct read-only	Shoppers enter codes but do not manage code records
Excel import/export	Direct	Codes live in the promotion_codes worksheet
Promotion services	Direct system-owned	Validation, uniqueness, and usage-limit logic live in services

Sources:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes/CreateDialog.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes/DetailsDialog.php
• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes/Block.php
• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php
• packages/framework/src/Imports/Promotions/PromotionCodesSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionCodesSheet.php
• packages/framework/src/Services/Promotion/PromotionCodeService.php

Channel-Level Field Coverage

Admin create dialog

The packaged create flow supports two modes:

• single
  • code
  • usage_limit
  • usage_limit_per_customer
• bulk
  • prefix
  • count
  • usage_limit
  • usage_limit_per_customer

Source:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes/CreateDialog.php

Admin details dialog

The packaged edit flow exposes:

• code
• usage_limit
• usage_limit_per_customer
• redemption history for the code

Source:

• packages/admin/src/Livewire/Admin/Settings/Promotion/Codes/DetailsDialog.php

Excel workbook

The promotion_codes sheet supports:

• id
• promotion_id
• code
• usage_limit
• usage_limit_per_customer
• action

Sources:

• packages/framework/src/Imports/Promotions/PromotionCodesSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionCodesSheet.php

Configuration And Data Model

Key model characteristics:

• soft-deletable
• promotion-owned
• usage-limit aware

Important fields:

Field	Purpose
promotion_id	owning campaign
code	shopper-entered redemption key
usage_limit	total global cap
usage_limit_per_customer	cap per customer account group

Important validation rules:

• codes must be unique
• codes must be alpha_dash
• usage-limit fields must be integers greater than or equal to 0

Sources:

• packages/framework/src/Models/PromotionCode.php
• packages/framework/src/Services/Promotion/PromotionCodeService.php

Relationships

PromotionCode directly relates to:

• promotion
• promotionRedemptions

Source:

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

Rules And Downstream Effects

Important rules and effects:

• usage limits are checked against the full customer account user set, not just one user record
• creating a code with an existing value fails validation
• deleting a code dispatches PromotionCodeDeleted
• storefront cart code application creates a PromotionRedemption and triggers promotion recalculation

Sources:

• packages/framework/src/Models/PromotionCode.php
• packages/framework/src/Services/Promotion/PromotionCodeService.php
• packages/framework/src/Services/Promotion/PromotionRedemptionService.php

Integrations And Automation

Excel

Promotion codes are directly represented in the promotions import/export workbook.

Sources:

• packages/framework/src/Imports/Promotions/PromotionCodesSheetImport.php
• packages/framework/src/Exports/Promotions/Sheets/PromotionCodesSheet.php

Storefront cart

The cart promotion section accepts a code string, then uses promotion services to create or remove redemptions.

Sources:

• packages/storefront/src/Livewire/Storefront/Cart/PromotionSection.php
• packages/framework/src/Services/Promotion/PromotionRedemptionService.php
• packages/framework/src/Http/Resources/Storefront/PromotionRedemptionResource.php

Where It Appears To End Users

PromotionCode is nested for both admins and shoppers.

It appears through:

• the promotion page's codes block in admin
• the storefront cart promotion section
• order-level promotion-redemption displays

Sources:

• packages/admin/resources/views/components/settings/promotion/codes/block.blade.php
• packages/storefront/resources/views/components/cart/promotion-section.blade.php
• packages/framework/src/Http/Resources/Storefront/PromotionRedemptionResource.php

Current Documentation Takeaways

• PromotionCode is the operational bridge between promotion configuration and real cart/order redemption.
• The packaged product supports both single-code and bulk-prefix generation.
• Usage limits and combinability validation happen at redemption time, not only when the code is created.

Open Questions

• This first pass did not identify a standalone top-level admin page for codes outside the nested promotion workflow.
• PromotionRedemption remains folded into this page and the promotion page because it is system-generated rather than directly authored.