Promotions & Discounts - Product Requirements Document

Version: 2.0 | Status: Final | Date: 2026-01-15

1. Overview

1.1 Purpose

Enable rental companies to create and manage promotional campaigns, discount codes, referral programs, and invoice-level discounts to drive customer acquisition, increase booking conversion, and reward loyalty.

1.2 Problem Statement

Currently, Toprent.app supports:

Marketing promotions (banners/announcements) via the promotions table for display purposes only
Manual invoice discounts (discount field with discountUnit PERCENT/AMOUNT) applied at billing time
Referral tracking links with discount percentages for Billion marketplace customers
Source tracking codes for marketing attribution (no functional discount application)

Critical Gaps:

No reusable promotional codes for customer checkout
No automated campaign management with time/quantity limits
No discount validation or application rules
No redemption tracking, ROI measurement, or campaign analytics
No customer eligibility rules or vehicle targeting
No integration between promotional codes and order pricing

1.3 Business Value

Value Area	Measurable Outcome	Measurement Method
Revenue Growth	15-25% increase in bookings during promoted low-demand periods	Booking volume comparison: promoted vs. non-promoted periods
Customer Acquisition	30% reduction in new customer acquisition cost through targeted first-order discounts	CAC calculation: marketing spend ÷ new customers via promo codes
Customer Retention	20% increase in repeat booking rate through loyalty and referral programs	Cohort analysis: repeat order rate for promo users vs. non-users
Marketing ROI	3:1 or higher attributed revenue to discount cost ratio	Campaign analytics: orders generated ÷ discounts given
Inventory Optimization	10 percentage point improvement in off-peak vehicle utilization	Category utilization rates during promotional periods
Operational Efficiency	90% reduction in manual discount processing time	Time study: before/after admin discount application workflow
Partner Revenue	15% of bookings attributed to partner/affiliate promotional codes	Partner attribution tracking in order data

1.4 Success Metrics

Metric	Definition	Baseline	Target	Measurement Method	Timeframe
Promo Code Redemption Rate	Codes redeemed ÷ codes distributed × 100	N/A (new feature)	15-25%	Redemption logs ÷ distribution records	6 months post-launch
Campaign ROI	Attributed revenue ÷ total discounts given	N/A	≥3:1	Order totals with promo codes ÷ discount amounts	Per campaign
New Customer Acquisition via Promos	First-time customers using promo codes	N/A	40% of new customers	Customer order history analysis	6 months
Referral Program Conversion	Referred visitors who complete booking	N/A	10% conversion rate	Referral link clicks → completed orders	6 months
Average Discount per Order	Mean discount amount applied	Manual: ~5% of orders	Automated: 25% of orders	Order discount field analysis	3 months
Code Validation Errors	Failed code applications due to eligibility	N/A	<5% invalid attempts	Error log analysis	Ongoing
Off-Peak Utilization Lift	Booking increase during promoted periods	45% utilization	55% utilization	Availability calendar analysis	Per campaign
Partner Attribution Rate	Orders with partner promo codes ÷ total orders	0%	15%	Partner code usage tracking	6 months

1.5 Target Users

User Role	Business Context	Primary Needs
Tenant Admins	Manage promotional strategy and budgets	Create campaigns, monitor ROI, control costs
Marketing Teams	Execute promotional campaigns	Generate codes, track attribution, optimize spend
Operators	Process customer bookings	Validate codes, explain discounts, handle exceptions
Customers	Complete rental bookings	Apply discounts, understand savings, share referrals
Partners/Affiliates	Generate bookings for commission	Distribute codes, track conversions, earn commissions

1.6 Scope

In Scope:

Promotional code lifecycle management (create, edit, activate, deactivate, delete)
Multiple discount types: percentage, fixed amount, free extras/services
Campaign constraints: date ranges, usage limits, minimum order values
Customer eligibility: first-time customers, segments, usage limits per customer
Vehicle targeting: categories, specific vehicles, exclusions
Discount stacking rules with seasonal pricing
Real-time code validation during checkout
Automatic discount application to order pricing
Redemption tracking and campaign analytics
Referral program with unique links and discount inheritance
Multi-tenant isolation with company and tenant-wide scopes
API endpoints for widget/marketplace integration

Out of Scope:

Dynamic/surge pricing (handled by Pricing Engine)
Loyalty points accumulation system (future enhancement)
AI-driven discount recommendations (future enhancement)
Multi-currency discount conversion
A/B testing frameworks (future analytics feature)
Email/SMS campaign distribution (uses Communications module)
Payment provider discount integrations (Stripe coupons, etc.)

2. User Stories

Tenant Admin Stories

Priority	Story	Acceptance Criteria
P0	As a tenant admin, I want to create promotional codes with percentage or fixed discounts so that I can run marketing campaigns	Code created with unique identifier, discount type/value, saved to tenant scope
P0	As a tenant admin, I want to set start/end dates for campaigns so that discounts expire automatically	Codes rejected outside date range with clear error message
P0	As a tenant admin, I want to limit total code usage so that I control campaign costs	Code rejects redemption when limit reached with appropriate error
P0	As a tenant admin, I want to restrict codes to first-time customers so that I incentivize acquisition	Code validates customer order history and rejects repeat customers
P1	As a tenant admin, I want to set minimum order value requirements so that discounts apply to qualified bookings	Code rejects orders below threshold with minimum amount displayed
P1	As a tenant admin, I want to target specific vehicle categories so that I promote underutilized segments	Code validates vehicle category and rejects non-matching bookings
P1	As a tenant admin, I want redemption and revenue analytics so that I measure campaign ROI	Dashboard displays redemption count, discount total, attributed revenue
P1	As a tenant admin, I want to deactivate codes mid-campaign so that I respond to changing needs	Code status changes immediately; existing orders unaffected
P2	As a tenant admin, I want per-customer usage limits so that I prevent abuse	Code tracks customer redemptions and enforces limit
P2	As a tenant admin, I want to export usage data so that I analyze customer behavior	CSV export with code, customer, order, discount, date fields

Marketing Team Stories

Priority	Story	Acceptance Criteria
P0	As a marketer, I want to generate partner referral links so that affiliates promote our services	Unique link generated with embedded code and referrer attribution
P0	As a marketer, I want to track which codes drive bookings so that I optimize spend	Analytics show redemption count, conversion rate, revenue per code
P1	As a marketer, I want custom code names so that I track multi-channel attribution	Code accepts custom alphanumeric names, validates uniqueness
P1	As a marketer, I want to clone campaigns so that I replicate successful promotions	Clone creates new code with copied settings, new unique identifier
P2	As a marketer, I want to schedule campaigns in advance so that I plan seasonal promotions	Start date can be set in future; code activates automatically

Operator Stories

Priority	Story	Acceptance Criteria
P0	As an operator, I want to validate promotional codes so that I confirm discount eligibility	Real-time validation returns success/error with specific reason
P0	As an operator, I want clear error messages so that I explain issues to customers	Error messages specify reason: expired, limit reached, not eligible, etc.
P0	As an operator, I want automatic discount application so that pricing is accurate	Discount calculated and applied to order total without manual entry
P1	As an operator, I want to see active discounts on orders so that I explain savings	Order details display discount code, type, and amount
P2	As an operator, I want to override restrictions in exceptional cases so that I handle service issues	Admin override available with audit logging

Customer Stories

Priority	Story	Acceptance Criteria
P0	As a customer, I want to enter promotional codes during checkout so that I receive discounts	Code input field available before payment; discount applies on submission
P0	As a customer, I want immediate feedback on code validity so that I know if it worked	Success shows discount amount; error shows specific reason
P0	As a customer, I want to see discount deducted from my total so that I understand savings	Order summary shows subtotal, discount line, final total
P1	As a customer, I want to share referral links so that friends and I both benefit	Unique referral link generated; discount applied to friend’s first order
P2	As a customer, I want to see eligible promotions so that I maximize savings	Available promotions displayed during checkout if criteria met

Partner/Affiliate Stories

Priority	Story	Acceptance Criteria
P0	As a partner, I want custom promotional codes so that I track referrals and earn commissions	Unique partner code created with referrer ID attribution
P1	As a partner, I want to see bookings from my codes so that I measure marketing impact	Partner dashboard shows redemption count and attributed bookings
P2	As a partner, I want notifications when codes are used so that I follow up with customers	Notification sent on redemption with order details

3. Functional Requirements

ID	Requirement	Priority	Business Outcome
FR-001	Create, read, update, and delete promotional codes	P0	Marketing can launch and manage campaigns
FR-002	Enforce unique, case-insensitive code identifiers	P0	Prevents customer confusion from duplicate codes
FR-003	Support percentage, fixed amount, and free service discount types	P0	Flexible promotional strategies for different campaigns
FR-004	Validate codes are active before applying	P0	Controlled campaign lifecycle
FR-005	Enforce campaign date range constraints	P0	Automatic campaign expiration without manual intervention
FR-006	Track usage and enforce maximum redemption limits	P0	Budget control and campaign cost management
FR-007	Enforce per-customer usage limits	P1	Prevents abuse and ensures fair distribution
FR-008	Validate minimum order value before applying discount	P1	Ensures discounts apply to qualified purchases
FR-009	Restrict codes to first-time customers when configured	P1	Targeted customer acquisition
FR-010	Filter by vehicle category eligibility	P1	Promote specific fleet segments
FR-011	Support company-specific and tenant-wide code scopes	P0	Multi-company promotional flexibility
FR-012	Configure stacking rules with seasonal pricing	P1	Clear discount combination policies
FR-013	Record redemption history with order and customer attribution	P0	Campaign performance tracking
FR-014	Calculate and apply discounts to order pricing	P0	Accurate automated pricing
FR-015	Display discount as separate line item on orders/invoices	P0	Customer transparency and accounting clarity
FR-016	Prevent code application after order confirmation	P0	Revenue protection
FR-017	Generate referral links with embedded promotional codes	P1	Partner and affiliate program support
FR-018	Track referrer attribution for referral redemptions	P1	Commission and reward calculation
FR-019	Provide code validation with detailed error responses	P0	Clear customer communication
FR-020	Expose redemption analytics for campaign reporting	P1	ROI measurement and optimization
FR-021	Support bulk generation of unique single-use codes	P2	Mass distribution campaigns
FR-022	Calculate discount before deposit to ensure accurate payments	P0	Correct payment processing

4. Acceptance Criteria

AC-001: Promotional Code Creation

Given I am a tenant admin
When I create a promotional code with code “SUMMER25”, type PERCENTAGE, value 25%, start 2026-06-01, end 2026-08-31, max usage 500
Then the code is saved with inactive status by default, scoped to my tenant, ready for activation

AC-002: Valid Code Application

Given an order for $200 within the valid date range
When customer applies active code “SUMMER25” (25% discount)
Then discount of $50 is calculated, order total becomes $150, redemption is recorded

AC-003: Expired Code Rejection

Given an order created on 2026-09-15
When customer applies code “SUMMER25” (expired 2026-08-31)
Then error “Promotional code has expired” is returned, no discount applied

AC-004: Usage Limit Enforcement

Given code “LAUNCH100” has reached 100/100 usage limit
When customer attempts to apply the code
Then error “Promotional code usage limit reached” is returned

AC-005: Minimum Order Value Enforcement

Given code “VIP50” requires minimum $300 order value
When customer applies to $250 order
Then error “Order must be at least $300 to use this code” is returned

AC-006: First-Time Customer Restriction

Given code “WELCOME20” restricted to first-time customers
When customer with 2 completed orders applies the code
Then error “This code is valid for first-time customers only” is returned

AC-007: Vehicle Category Targeting

Given code “LUXURY15” valid only for “luxury” category
When applied to “economy” vehicle
Then error “This code is not valid for the selected vehicle” is returned
When applied to “luxury” vehicle
Then discount is applied successfully

AC-008: Stacking Rule - Disallowed

Given code “STACK10” disallows stacking, order has seasonal surcharge
When customer applies the code
Then error “This code cannot be combined with other discounts” is returned

AC-009: Stacking Rule - Allowed

Given code “EXTRA5” (5%) allows stacking, order is $200 base + 20% seasonal ($240)
When customer applies the code
Then discount applies to $240, final total is $228

AC-010: Referral Link Generation

Given I am a partner
When I request a referral link with 10% discount
Then unique link generated (e.g., /book?ref=PARTNER_ABC123), code created with my referrer ID

AC-011: Referral Redemption

Given new customer clicks referral link and completes first booking
Then promotional code auto-applied, discount calculated, referrer ID recorded, commission credited

AC-012: Invoice Display

Given order with “SAVE30” applied ($300 base, $90 discount)
When viewing order or invoice
Then line items show: Subtotal $300.00, Promotional Discount (SAVE30) -$90.00, Total $210.00

AC-013: Mid-Campaign Deactivation

Given active code “FLASH24H” with 50 redemptions
When admin deactivates the code
Then new applications rejected, existing orders unchanged, redemption count frozen at 50

AC-014: Analytics Dashboard

Given viewing promotions dashboard for 2026-07-01 to 2026-07-31
Then each code shows: redemption count, total discount amount, attributed revenue, average order value, conversion rate; CSV export available

AC-015: Per-Customer Limit Enforcement

Given code “MONTHLY10” allows 1 use per customer
When customer A applies to second order after first successful use
Then error “You have already used this promotional code” is returned

5. Business Rules

Discount Calculation

Calculate base vehicle price from tariff matrix
Apply seasonal pricing adjustments
Add extra services and delivery fees (subtotal)
Apply promotional code discount to subtotal
Calculate final total with VAT

Discount Constraints

Percentage discounts: 1% to 100%
Fixed amount: Cannot reduce total below zero
Only one promotional code per order

Code Lifecycle

Draft: Created, not redeemable
Active: Available for redemption
Paused: Temporarily disabled
Expired: Past end date, read-only
Exhausted: Usage limit reached
Deleted: Soft-deleted, history retained

Usage Tracking

Usage increments on order confirmation
Canceled orders don’t count toward limits
Refunded orders decrement usage count

Customer Eligibility

First-time customer = zero completed orders
Eligibility checked at code application time

Multi-Company Behavior

Company-specific codes: vehicles in specified company only
Tenant-wide codes: all companies in tenant

Referral Rules

Referral codes prefixed “REF_” + unique ID
Invitee receives discount on first order only
Self-referrals blocked

Code Security

Minimum 4 characters
Alphanumeric plus hyphens and underscores only
Case-insensitive matching
Rate-limited validation attempts

Validation Order

Code exists and not deleted
Code is active
Within date range
Usage limit not exceeded
Customer eligibility met
Vehicle eligibility met
Minimum order value met
Stacking rules compatible

6. Dependencies

Dependency	Integration Point	Impact
Dynamic Pricing Engine	Discount applied after seasonal adjustments	Required for accurate pricing
Order/Reservation System	Code validation and application during checkout	Required for redemption flow
Payment Processing	Deposit calculated on discounted total	Required for correct payments
Customer Management	Order history for first-time validation	Required for eligibility rules
Communications	Promotional code distribution	Optional for marketing
Analytics/Reporting	Campaign performance dashboards	Required for ROI tracking
Authentication	Role-based access to promotion management	Required for security

7. Glossary

Term	Definition
Promotional Code	Alphanumeric string customers enter to receive discounts
Campaign	Marketing initiative with promotional codes and defined objectives
Redemption	Successful application of promotional code to an order
Stacking	Combining promotional discount with seasonal pricing
Referral Link	URL with embedded promotional code for tracking referrals
Usage Limit	Maximum redemptions allowed (global or per-customer)
Attributed Revenue	Total order value from orders using a promotional code
ROI	Attributed revenue ÷ discount amount given
First-Time Customer	Customer with zero completed orders

Document History:

v1.0 (2026-01-09): Initial draft
v2.0 (2026-01-15): Converted to business-focused format with measurable outcomes, success metrics, consolidated requirements, prioritized user stories