Promotion Laravel Package

Product Decisions This Supports

• Build vs. buy for pricing/promotion mechanics. A promotion engine is deceptively complex (eligibility rules, stacking/exclusivity, priority ordering, rounding, tax interaction, scheduling windows). Adopting a module avoids spending 4–8 engineer-weeks re-deriving those semantics for an MVP.
• Feature roadmap: campaign and discount capabilities. Enables coupon codes, percentage/fixed cart discounts, product-level adjustments, time-boxed sales, and first-order or segment-based offers — the standard table stakes for a commerce roadmap.
• Scope decisions on merchandising vs. pricing. Separates "what we sell" (catalog) from "how we price it" (promotions), letting pricing experiments ship without catalog changes.
• Use cases to target: Laravel-based DTC storefronts, B2B quote/order flows with tiered or contract pricing, internal admin/back-office tools, and marketplace seller-funded discounts.
• Buy-vs-integrate: Informs whether to self-host promo logic (this package) versus paying per-redemption for a SaaS coupon platform — a cost-curve decision that scales with order volume, not seats.

When to Consider This Package

Consider it when:

• You are already on Vanilo, or are actively evaluating it as your Laravel commerce foundation. This module is designed against Vanilo's cart/order/checkout abstractions; that is where most of its value lives.
• You want MIT-licensed, self-hosted, Eloquent-native promotion primitives with no per-coupon or per-redemption fees.
• Your team is fluent in Laravel and prefers composable packages over a monolithic commerce platform.
• You need promo capabilities in the near term and can absorb the integration risk with a spike.

Look elsewhere when:

• You are not on Vanilo. The abstractions won't map cleanly, and you'll pay an integration tax for little gain.
• You need an enterprise rule engine (complex eligibility DSLs, arbitrage-grade stacking, multi-currency/multi-tenant governance) — evaluate dedicated engines or SaaS (e.g., Voucherify, Open Loyalty) instead.
• You need promotion analytics, A/B testing, or attribution out of the box; this is a mechanics module, not a growth platform.
• Maturity signals matter to your org. Stars (1) and dependents (0) are weak on their own — but for sub-packages split from a larger framework, this often reflects a monorepo-split artifact rather than abandonment. Verify against the upstream Vanilo repository's commit cadence, release tags, and issue activity before ruling it out. If you need a vendor SLA or a large community, this is not that.
• Alternative paths to weigh: other Laravel commerce stacks with their own promo modules, or a thin in-house discount layer if your rules are genuinely simple (single-code, percentage-off only).

How to Pitch It (Stakeholders)

To executives: This is a small, MIT-licensed module that supplies the promotion and discount mechanics most commerce products eventually need — coupons, cart discounts, time-boxed offers. The business case is time-to-market and avoided build cost, not licensing savings: it can compress a multi-week pricing workstream into days. The risk is contained because it sits behind Vanilo's cart/order interfaces and can be replaced or forked. Recommendation: fund a 1–2 day technical spike, not a commitment. The package's public adoption signals are thin, so we should validate maintainability and fit before it enters the critical path.

To engineering: Idiomatic Laravel package — service provider, Eloquent models, config-driven, integrates into the Vanilo cart/order pipeline. Small surface area, so forking or patching is realistic if upstream stalls. Two things to check in the spike: (1) version coupling to the Vanilo core you plan to pin, and (2) whether its stacking, priority, and rounding semantics match our pricing policy — that's where mismatches get expensive later.

Decision requested: Approve a short evaluation spike with a clear go/no-go on rule semantics and upstream maintenance health.