Promo Codes and Discounts

Promo codes are a powerful marketing tool that lets you offer discounts to attract new customers, reward loyal riders, and run promotional campaigns. This guide covers everything you need to know about creating, managing, and optimizing promo codes.

Overview

Promo codes provide discounts that customers can apply to rides, wallet top-ups, or subscription purchases. Each code can be configured with specific discount amounts, usage limits, validity periods, and targeting options.

Key Features

• Percentage or fixed discounts - Offer a percentage off or a fixed dollar amount
• Multiple application types - Apply to rides, wallet credits, or subscriptions
• Usage limits - Control total uses and per-customer limits
• Location targeting - Restrict codes to specific subaccounts
• Vehicle type filtering - Limit codes to specific vehicle models
• Minimum spend requirements - Require a minimum subtotal before discount applies
• Maximum discount caps - Prevent percentage discounts from exceeding a set amount

Accessing Promo Codes

Promo Code Configuration

Code

The unique identifier customers enter to redeem the discount.

Discount Type

Choose how the discount is calculated:

Fixed Amount Calculation:

Discount = Fixed Amount
Example: Subtotal $12.00, Code $5.00 off = Discount $5.00 = Final $7.00

Percentage Calculation:

Discount = Subtotal x (Percentage / 100)
Example: Subtotal $12.00, Code 20% off = Discount $2.40 = Final $9.60

Discount Value

The actual discount amount based on the type selected:

Application Type

Specify where the promo code can be used:

Wallet Credit Behavior:

• When redeemed, the discount value is added to the customer's wallet balance
• The credit can then be used on any future rides
• Works like a gift card or bonus credit

Ride Discount Behavior:

• Applied during ride billing after dynamic pricing
• Only affects the specific ride where the code is used
• Appears in the ride's pricing breakdown

Subscription Discount Behavior:

• Reduces the cost of purchasing a subscription plan
• Applied at the time of subscription purchase

Usage Limits

Total Uses (Global)

Maximum number of times the code can be used across all customers.

Use Cases:

• Limited-time flash sales (first 50 customers)
• Exclusive event promotions
• Budget-controlled campaigns

Uses Per Customer

Maximum times a single customer can use the code.

Best Practices:

• First-ride discounts: Set to 1
• Loyalty rewards: Allow multiple uses
• Referral codes: Set to 1 per customer

Validity Period

Valid From

Date and time when the code becomes active.

Codes cannot be redeemed before this date.

Valid Until (Optional)

Date and time when the code expires.

Common Scenarios:

• Weekend sale: Friday 5 PM to Sunday 11:59 PM
• Holiday promo: December 20 to December 31
• Summer campaign: June 1 to August 31

Targeting Options

Location (Subaccount)

Restrict the code to a specific operating location.

Use Cases:

• City-specific launches
• Location-based partnerships
• Local event promotions

Vehicle Types (Advanced)

Limit the code to specific vehicle models. This is configured in the database and available for advanced use cases.

Example:

• Premium vehicle promotion: Only applies to e-bikes
• Scooter launch discount: Only applies to scooters

Minimum Spend Requirement

Set a minimum subtotal the customer must reach before the code applies.

How It Works:

If Subtotal >= Minimum:
  Apply discount
Else:
  Reject promo code

Use Cases:

• "$5 off rides over $15" - Encourages longer rides
• "20% off $25+ rides" - Protects margins on small rides

Maximum Discount Cap

Limit the maximum discount for percentage-based codes.

How It Works:

Raw Discount = Subtotal x (Percentage / 100)
Final Discount = MIN(Raw Discount, Max Discount Cap)

Example: 50% off with $10 max:

• $12 ride: 50% = $6.00, Discount: $6.00 (under cap)
• $30 ride: 50% = $15.00, Discount: $10.00 (capped)

Use Cases:

• Generous percentage discounts without unlimited liability
• "50% off, up to $10" style promotions

Creating a Promo Code

Step 1: Basic Information

Code (Required)

• Enter a unique code or click Generate for a random 8-character code
• Codes are case-insensitive and stored uppercase

Application Type (Required)

• Select where the code can be used: Wallet Credit, Ride Discount, or Subscription Discount

Step 2: Configure Discount

Discount Type (Required)

• Choose Fixed Amount or Percentage

Discount Value (Required)

• Enter the amount (e.g., 5.00 for $5 or 20 for 20%)

Step 3: Set Limits

Total Uses (Optional)

• Enter maximum global uses or leave blank for unlimited

Uses Per Customer (Optional)

• Enter per-customer limit (defaults to 1)

Step 4: Set Validity

Valid From (Required)

• Select when the code becomes active (defaults to now)

Valid Until (Optional)

• Select expiration date or leave blank for no expiration

Step 5: Add Details

Description (Optional)

• Internal description for reference (e.g., "Summer 2025 new user promo")

Location (Optional)

• Select a specific location or leave as "All Locations"

Step 6: Create

Click Create to save the promo code. It will be immediately active if the valid_from date has passed.

Managing Promo Codes

Viewing Codes

The promo codes table displays:

Editing Codes

1. Click the Edit (pencil) icon
2. Modify any fields
3. Click Save

Cloning Codes

Use the Clone button to create a similar code:

1. Click the Clone icon on an existing code
2. A new form opens with all settings copied except the code itself
3. Enter a new unique code
4. Adjust any other settings
5. Click Create

Use Cases:

• Creating location-specific variants of a campaign
• Rolling over expiring codes with new dates
• A/B testing different discount values

Deactivating Codes

Toggle the Active switch to disable a code:

• Inactive codes cannot be redeemed
• Code remains in the system for historical reference
• Can be reactivated anytime

Use For:

• Pausing campaigns temporarily
• Ending promotions early
• Preparing codes for future activation

Deleting Codes

1. Click the Delete (trash) icon
2. Confirm deletion

How Promo Codes Are Applied

Billing Position

Promo codes are applied after all other pricing calculations:

Base Charges -> Tier Benefits -> Subscription -> Packages -> Dynamic Pricing -> PROMO CODE -> Final

This means the promo discount applies to the amount remaining after other discounts and adjustments.

Validation Process

When a promo code is submitted, the system checks:

1. Code exists - The code is in the database
2. Code is active - The is_active flag is true
3. Time validity - Current time is within valid_from and valid_until
4. Global limit - Total uses haven't exceeded max_uses
5. Customer limit - Customer uses haven't exceeded max_uses_per_customer
6. Location match - If scoped, the ride's subaccount matches
7. Vehicle match - If scoped, the vehicle type matches
8. Minimum met - Subtotal meets min_ride_amount requirement

If any check fails, the code is rejected with an appropriate error message.

Discount Calculation

If discount_type = 'percentage':
  Raw Discount = Subtotal x (Percentage / 100)
Else:
  Raw Discount = Fixed Amount

If max_discount set:
  Discount = MIN(Raw Discount, Max Discount Cap)

Final Discount = MIN(Discount, Subtotal)  // Can't exceed subtotal

Common Scenarios

Scenario 1: New User Discount

Goal: Give new customers $5 off their first ride

Setup:

• Code: WELCOME5
• Type: Ride Discount
• Discount: Fixed $5.00
• Uses per customer: 1
• Location: All Locations
• Valid: No expiration

Scenario 2: Summer Flash Sale

Goal: 25% off all rides this weekend, capped at $10

Setup:

• Code: SUMMER25
• Type: Ride Discount
• Discount: 25%
• Max Discount: $10.00
• Total Uses: 500 (first 500 only)
• Valid From: Friday 5 PM
• Valid Until: Sunday 11:59 PM

Scenario 3: Wallet Bonus

Goal: Add $10 credit to customer's wallet

Setup:

• Code: BONUS10
• Type: Wallet Credit
• Discount: Fixed $10.00
• Uses per customer: 1
• Location: All Locations

Scenario 4: Premium E-Bike Promotion

Goal: 15% off premium e-bike rides only

Setup:

• Code: EBIKE15
• Type: Ride Discount
• Discount: 15%
• Vehicle Types: Premium E-Bike model ID
• Uses per customer: Unlimited
• Valid: 30 days

Scenario 5: Minimum Spend Promotion

Goal: $3 off rides over $12

Setup:

• Code: SAVE3
• Type: Ride Discount
• Discount: Fixed $3.00
• Minimum Ride Amount: $12.00
• Uses per customer: Unlimited

Best Practices

Code Design

1. Keep codes simple - Easy to remember and type
2. Use meaningful prefixes - SUMMER_, LAUNCH_, REF_ for organization
3. Avoid confusion - Skip O/0, I/1/l characters
4. Test before launch - Verify codes work in your test environment

Discount Strategy

1. Start conservative - Begin with smaller discounts and increase if needed
2. Set maximum caps - Protect against unexpectedly large discounts
3. Use minimum spends - Encourage larger rides while offering value
4. Track performance - Monitor usage to measure campaign effectiveness

Usage Limits

1. Always set per-customer limits - Prevent abuse
2. Consider total caps - Budget-friendly campaigns
3. Plan for fraud - Watch for unusual patterns

Timing

1. Schedule in advance - Set valid_from for future campaigns
2. Use expiration dates - Create urgency and prevent stale codes
3. Allow buffer - Start codes slightly early for testing

Technical Reference

Database Table: promo_codes

Database Table: customer_promo_uses

Tracks individual customer usage of promo codes.

Troubleshooting

Code Not Working

1. Check active status - Ensure is_active is true
2. Verify dates - Current time must be between valid_from and valid_until
3. Check limits - Verify global and per-customer limits aren't reached
4. Check location - If scoped, ensure ride is at the correct subaccount
5. Check minimum - Ensure subtotal meets minimum ride amount
6. Check application type - Ensure code type matches usage context

Discount Amount Incorrect

1. Check discount type - Percentage vs fixed calculation differs
2. Verify max cap - Percentage discounts may be capped
3. Check subtotal - Discount can't exceed the subtotal amount
4. Review billing order - Promo applies after other discounts

Customer Says Code Was Already Used

1. Check customer_promo_uses for their usage records
2. Verify max_uses_per_customer setting
3. Look for multiple ride records with the same promo

Usage Count Seems Wrong

1. uses_count is incremented each time the code is applied
2. Check customer_promo_uses for the actual usage records
3. The count may differ if there were failed transactions