User Journeys

This document provides comprehensive user journey flows for both administrators and consumers in the Coupons feature, based on the implementation in Farfalla.

Administrator Journey: Coupon Management

1. Accessing Coupon Management

Entry Points:

• Navigate to Dashboard → Coupons
• Direct URL: /dashboard/coupons

Prerequisites:

• Admin user with appropriate permissions
• Feature flag Discount Coupons must be enabled for the tenant

2. Coupon Creation Flow

2.1 Opening Creation Modal

1. Click "New Coupon" button on coupons dashboard
2. System opens "Create New Coupon" modal with form sections

2.2 Basic Information (Required)

• Code: Enter custom code or click generator button for unique code
  • Allowed characters: A-Z, 0-9, dot (.), hyphen (-), underscore (_)
  • System normalizes to uppercase slug on save
  • Validates uniqueness across tenant
• Discount Percentage: Enter value with up to 2 decimals
  • Range: 0.01-100% (with restrictions based on configuration)
  • For subscriptions with limited periods: max 99.99%

2.3 Coupon Application (Required)

Select applicable product types:

• Individual Sales (Issues): One-time product purchases
  • Optional: Select specific products or leave empty for all
  • System shows product selector when enabled
• Subscriptions (Plans): Recurring subscription plans
  • Optional: Select specific plans or leave empty for all
  • Configure discounted periods (unlimited or specific number)

2.4 Usage Restrictions (Optional)

Configure limits (0 = unlimited):

• Total Usage: Maximum redemptions across all users
• Uses per User: Maximum redemptions per individual user
• Uses per Issue: Maximum redemptions per publication
• End-of-redeem-month Expiration: Redemptions expire at month end

2.5 Expiration Settings (Optional)

• Valid Until: Set expiration date for the coupon code
• Discounted Periods: For subscriptions only
  • Unlimited periods: Allow 100% discount
  • Limited periods: Cap at 99.99% discount

2.6 Saving Process

1. Click "Create Coupon" button
2. System validates all inputs
3. Creates relationships if specific items selected
4. Returns success confirmation
5. Closes modal and refreshes coupon list

3. Coupon Management Operations

3.1 Viewing Coupon List

• Displays paginated list (15 per page) ordered by creation date
• Shows: Code, Discount %, Status, Creation Date, Valid Until, Usage Count, Application Scope
• Supports search by coupon code
• Excludes gift coupons from main list

3.2 Editing Coupons

1. Click edit action from coupon row menu
2. Opens edit modal with current values populated
3. Code field is read-only (cannot be changed)
4. All other fields are editable
5. System updates couponables relationships as needed
6. Returns 204 status on successful update

3.3 Deleting Coupons

1. Click delete action from coupon row menu
2. System performs soft delete (sets deleted_at timestamp)
3. Coupon becomes inactive but remains visible in admin lists
4. Cannot be redeemed by consumers after deletion

3.4 Bulk Operations

• Create multiple coupons simultaneously
• Uses background processing for large batches

4. Export and Reporting

4.1 Export Options

Access from Exports dropdown:

• Per-Coupon Usage: Transaction-level usage for specific coupon
• Overall Usage: Transaction-level usage across all coupons

4.2 Export Process

1. Select export type from dropdown
2. System queues background job for generation
3. Excel file (.xlsx) generated asynchronously
4. Email sent with time-limited download link

Consumer Journey: Coupon Redemption

1. Coupon Application Entry Points

1.1 Cart-Based Redemption

• Location: Shopping cart page
• Component: Coupon Input component
• Supports: Multiple items with single coupon code

1.2 Plan-Based Redemption

• Location: Individual plan/subscription pages
• Component: PaymentLinks Vue component
• Supports: Direct application to specific plan

1.3 Issue-Based Redemption

• Location: Individual issue purchase pages
• Integration: Cart system or direct checkout

2. Coupon Entry and Validation Flow

2.1 Code Entry Process

1. Consumer locates coupon input field
2. Enters coupon code (case-insensitive input)
3. Clicks "Apply" or presses Enter
4. System processes code

2.2 Real-Time Validation Chain

Step 1: Basic Code Validation

• Code exists in database and is not soft-deleted
• Code has not expired

Step 2: Usage Limit Validation

• Checks if the coupon has reached its total usage limit
• For logged-in users, verifies they haven't used this coupon too many times
• For issue purchases, ensures the coupon hasn't been used too many times on that specific issue

Step 3: Product Type Validation

• Coupon enabled for product type (issues/plans)
• Coupon is valid for the type of product being purchased (issues or subscription plans)

Step 4: Specific Assignment Validation

• Verify if the coupon can be used on this specific product (some coupons are restricted to certain items only)
• Check user assignment if coupon restricted to specific users
• Validate issue assignment if applicable

Step 5: Business Rule Validation

• Retail-licensed issues rejected
• Private plans without prices only accept 100% coupons
• Multiple items with 100% coupon rejected

2.3 Validation Response Handling

Success Path:

1. Discount applied to eligible items
2. Visual feedback shows applied discount
3. Price updates reflect discount
4. Coupon code displayed as "applied"

Error Path:

1. Error message displayed to user
2. Common messages:
   • "Unable to find a valid discount..."
   • "The titles do not meet the requirements..."
   • "The total discount code is not valid for use with multiple titles..."
3. Coupon input field cleared or highlighted
4. User can retry with different code

3. Checkout Integration

3.1 Discount Application Logic

• Items sorted by price (descending) for optimal business logic
• Coupon uses consumed in order of item value
• Each applicable item consumes one use from global limit
• Discount calculated per item based on coupon percentage

3.2 Price Calculation

• Original price × (1 - discount_percentage/100)
• Result enforced to meet store minimum amount
• 100% discounts result in free checkout flow

3.3 Checkout Flow Variations

Standard Discount (< 100%):

1. Prices updated with discount applied
2. Proceed to payment gateway selection
3. Normal payment processing
4. Coupon use count incremented on success

Total Discount (100%):

1. Single item: Immediate free checkout
2. Multiple items: Error - not supported
3. Skip payment gateway
4. Direct order processing
5. Coupon use count incremented immediately

4. Special Considerations

For information about gift coupons, which operate differently from regular discount coupons, see the dedicated Gift Coupons documentation.

Error Handling and Edge Cases

Administrator Errors

• Duplicate Code: Validation prevents duplicate codes within tenant
• Invalid Percentage: Range validation based on configuration
• Missing Required Fields: Form validation prevents submission
• Permission Errors: 403 response if tenant lacks required permissions

Consumer Errors

• Expired Codes: Checked against valid_to date
• Depleted Codes: Usage count validation against limits
• Ineligible Products: Product type and assignment validation
• Authentication Required: Some validations require logged-in user
• Retail Content: Special handling for retail-licensed content

Technical Implementation Notes

Database Operations

• Coupon usage tracked via uses column increment
• Soft deletes preserve historical data
• Couponables table manages many-to-many relationships
• Activity logging tracks all coupon changes

Performance Considerations

• Coupon validation cached where possible
• Background job processing for bulk operations
• Paginated admin interfaces for large datasets
• Efficient query patterns for validation chains

Security Features

• Tenant isolation for all coupon operations
• Permission-based access control
• Input sanitization and validation
• Rate limiting on coupon validation attempts

This comprehensive user journey documentation reflects the actual implementation in Farfalla and provides clear guidance for both administrators managing coupons and consumers redeeming them.