Tomato Coupons Module Laravel Package

Product Decisions This Supports

• Build vs. buy on promotions (v1 scope). This package lets you ship coupon codes, percentage/fixed discounts, expiry, and usage caps without allocating a sprint to coupon CRUD, admin screens, and migrations. If promos are table stakes for launch rather than a differentiator, adopting it converts a multi-week build into an integration task — worth roughly 2–4 engineer-weeks of avoided scope, offset by integration and QA time.
• Feature sequencing inside a promotions roadmap. The package covers the "foundation" tier — code creation, discount type, expiration, activation, usage limits. It does not cover the tiers that usually drive revenue: stacking rules, product/category eligibility, per-customer segmentation, BOGO, tiered or cart-level thresholds. Treat it as Tier 1 and be explicit that Tiers 2–3 remain custom work on top.
• Launch-readiness decisions for a TomatoPHP storefront. If you're already on the TomatoPHP/Filament admin stack, this closes a known gap (no promo capability) at near-zero architectural cost. If you're not on that stack, it forces a decision on adopting an admin ecosystem to get one feature — almost always the wrong trade.
• Roadmap de-risking via a service boundary. The recommended pattern (wrap validation in your own CouponService, store discount as a cart/order adjustment, record usage in the order-completion transaction) means the buy decision is reversible. You can start here and swap in a standalone promotions engine later without rewriting checkout, because your domain logic lives in your code, not the package's.
• Operational/GTM decisions. Marketing and support need a coupon lifecycle — who creates codes, who can deactivate vs. delete, how refunds interact with a discount already applied, what "expired" means in the customer's timezone. This package gives you the CRUD surface; the policy is a product decision you still own.
• Priority signal on maintenance. Zero stars, zero dependents, one contributor, a last release (March 2024) that was translation-only. That is not a reason to reject on its own — it's a reason to price in self-support and to avoid coupling your differentiated logic to it.

When to Consider This Package

Adopt when all of these hold:

• You are already running TomatoPHP and/or a Filament admin panel at a compatible major version. This is close to a hard prerequisite; the package's value is largely its pre-built admin resource, which is worthless outside that ecosystem.
• Your promo needs are Tier 1 — percentage and fixed-amount codes, expiry, global and per-user caps, active/inactive. Anything involving stacking, eligibility by SKU/category, or multi-tenant scoping should be validated against the actual schema before committing.
• You have Laravel engineers who are comfortable reading vendor source. With no meaningful docs site, low adoption, and no issue history to learn from, the migrations and Filament resource are the documentation.
• You can own the checkout policy yourself. You need a team able to write and test the validation service, concurrency handling on limited-use codes, rounding rules, and timezone-safe expiry. The package supplies persistence, not policy.
• You can absorb the risk of a young, thinly-adopted dependency — a fork-and-maintain posture, or a genuine ability to rip it out.

Look elsewhere (or build) when:

• You're not on TomatoPHP/Filament. The admin UI is the main deliverable; without the host stack you're taking a dependency for a handful of models and migrations.
• Promotions are a core differentiator. Discount engines get deep fast — stacking, proration on partial refunds, tax treatment, eligibility matrices, multi-currency. You will outgrow a Tier-1 module and end up forking it, which is worse than building the boundary correctly from day one.
• You need vendor SLAs, security review artifacts, or a support contract. There is no evidence of any of these. Zero dependents means nobody else has stress-tested the upgrade path.
• You need multi-tenancy or complex currency handling. Not evidenced in the described surface; verify before assuming.
• Your expiry/refund/compliance semantics are non-standard. Regulatory or accounting rules around discounts are easier to encode in your own service than to retrofit.

Practical gate before committing: timebox a spike. Install in staging, publish config and migrations, create a fixed-amount coupon end-to-end (admin → checkout field → server-side validation → cart adjustment → usage row on paid order), and confirm money representation (integer minor units vs. decimal), rounding direction, and expiry timezone behavior. If that spike is clean in under a week, adopt. If it surfaces schema gaps, stop — the cost curve bends sharply after the first custom field.

How to Pitch It (Stakeholders)

For executives — the one-paragraph version: We have a gap: no way to run promotions. Building coupon management from scratch is roughly 2–4 engineer-weeks of undifferentiated work — admin screens, discount math, expiry logic, usage caps. An MIT-licensed Laravel module already does that, and it plugs directly into the admin panel we're already running. The trade is real but bounded: it's a small, young, single-maintainer project with no other adopters, so we treat it as a starting point we own rather than a vendor we depend on. We keep our checkout logic in our own service layer, which means if the package stalls or we outgrow it, we replace the storage layer and keep the business logic. Recommendation: adopt behind a spike, scope it to Tier-1 promos, and budget a small reserve for self-maintenance.

For engineering — what we're actually asking for: Integrate, don't extend-in-place. Own a CouponService that encapsulates all validation policy; never let checkout call the model directly. Apply discounts as order adjustments with the code and computed amount persisted at time of purchase — never mutate the total. Write usage rows inside the order-completion transaction with row locking or atomic increments so concurrent checkouts can't overspend a limited code. Extend the Filament resource from a service provider; never patch vendor/. Publish lang files to the app and override there. Add the vendor:publish step to the deploy script — migrations aren't auto-loaded, and skipping it fails at runtime, not at boot, which will burn an afternoon in triage.

For finance/support — what changes operationally: Deactivating a coupon must replace deleting it, so usage history and order references stay intact. We need one documented definition of expiry (recommend end-of-day in the customer's timezone, not a precise UTC instant) and one documented refund rule for orders that used a code. Support needs a runbook: how to check whether a code is live, how to tell a customer why their code was rejected, and who has authority to alter a live promotion.

Risks to name out loud, briefly: thin adoption and a stale release cadence (translation-only in March 2024) mean no community upgrade testing; Filament major-version coupling is the likely future blocker, not the coupon logic itself; and the money-representation and rounding questions are boring and expensive if we get them wrong. None of these are reasons to not start — they're reasons to start with the service boundary in place.