Monetization

Start earning money.

Monetization

Start earning money.

DirectoryFast v1.6.0 introduces a comprehensive monetization platform that transforms your directory into a revenue-generating business. This complete guide covers all monetization features and their implementation.

Overview

The monetization system provides three primary revenue streams:

🚀 Paid Submissions - Express and Premium submission tiers
📺 Advertising Platform - Strategic ad placements throughout your site
⭐ Featured Products - Enhanced visibility for listings

All payments are processed securely through Polar with webhook-driven automation.

Quick Start

Prerequisites

Active Polar account with organization setup
DirectoryFast v1.6.0 or higher
Database migrations applied (pnpm prisma db push)

Essential Setup

Configure Polar Integration

# Production environment
POLAR_ACCESS_TOKEN_PROD=your-production-access-token

# Sandbox environment
POLAR_ACCESS_TOKEN_SANDBOX=your-sandbox-access-token

# Shared webhook secret
POLAR_WEBHOOK_SECRET=your-webhook-secret

Admin Configuration
- Navigate to /dashboard/admin/settings/features to enable monetization features
- Access /dashboard/admin/monetization for product management
- Configure sandbox/production mode via database settings
Sync Products from Polar
- Navigate to /dashboard/admin/monetization
- Click "Sync from Polar" to import all products
- Assign feature types to enable specific monetization features
Enable Features
- Configure advertising in /dashboard/admin/settings/features
- Set paid submission preferences
- Test webhook endpoints

Paid Submissions System

Overview

The paid submissions system offers tiered pricing for different review speeds and benefits, allowing users to pay for faster processing and enhanced visibility.

Submission Tiers

Free Submission (Default)

Processing Time: 7-14 days
Review Type: Manual review process
Placement: Standard listing placement
Features: Basic submission form
Admin Control: Can be disabled globally

Express Submission

Processing Time: 24-48 hours
Review Type: Priority review queue
Placement: Standard listing placement
Features: Fast-track processing
Pricing: Configurable via Polar products

Premium Submission

Processing Time: Same day
Review Type: Priority review with enhanced features
Placement: Featured placement for 7 days
Features: Social media promotion, priority support
Pricing: Premium tier via Polar products

Configuration

Create Polar Products
- Express Submission: Create product with appropriate pricing
- Premium Submission: Create premium-tier product
Assign Feature Types
- Navigate to /dashboard/admin/monetization
- Assign express_submission and premium_submission feature types
Enable/Disable Free Submissions
- Configure in /dashboard/admin/settings/features
- Toggle free submission availability

Implementation

// Submission checkout flow
const handleSubmissionCheckout = async (submissionType: SubmissionType) => {
  const response = await fetch('/api/submit-paid', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      productData,
      submissionType
    })
  });
  
  const { checkoutUrl } = await response.json();
  if (checkoutUrl) window.location.href = checkoutUrl;
};

Advertising Platform

Overview

The advertising platform provides strategic ad placements throughout your directory with simple monthly flat-rate pricing.

Ad Placement Types

Homepage Hero Banner

Location: Prime banner placement on homepage
Capacity: Up to 4 concurrent ads
Visibility: Maximum exposure
Feature Type: ads_homepage_hero

Product Page Sidebar

Location: Right sidebar on product detail pages
Capacity: Up to 4 concurrent ads
Visibility: Targeted product viewers
Feature Type: ads_product_page

Blog Sidebar

Location: Right sidebar on blog posts
Capacity: Up to 4 concurrent ads
Visibility: Content readers
Feature Type: ads_blog_sidebar

Collection Page Banner

Location: Top banner on collection pages
Capacity: Up to 4 concurrent ads
Visibility: Category browsers
Feature Type: ads_collection_page

Category Page Banner

Location: Top banner on category pages
Capacity: Up to 4 concurrent ads
Visibility: Category-specific audience
Feature Type: ads_category_page

Campaign Management

Campaign Creation

Title: Campaign name for admin tracking
URL: Target landing page
Image: Banner creative (optimized sizes)
Placement: Select from available placements
Duration: Monthly billing cycle

Approval Workflow

Submission: User submits campaign with payment
Review: Admin reviews content and approves
Activation: Campaign goes live after approval
Monitoring: Track performance and compliance

Implementation

// Ad campaign checkout
const handleAdCampaign = async (campaignData: AdCampaignData) => {
  const response = await fetch('/api/ads/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ campaignData })
  });
  
  const { checkoutUrl } = await response.json();
  window.location.href = checkoutUrl;
};

Featured Products

Overview

Traditional featured listings that provide enhanced visibility and priority placement throughout the directory.

Features

30-day featured placement in dedicated sections
Enhanced visibility in search results
Priority placement in category listings
Automatic expiration and renewal notifications
Revenue tracking and performance analytics

Configuration

Create Featured Product in Polar dashboard
Assign featured feature type in monetization settings
Configure pricing and duration
Enable feature in admin settings

Implementation

// Featured product checkout
const handleFeaturedProduct = async (productId: string) => {
  const response = await fetch('/api/feature-product', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ productId })
  });
  
  const { checkoutUrl } = await response.json();
  window.location.href = checkoutUrl;
};

Admin Dashboard

Settings Organization

NEW in v1.6.0: Settings are now organized into separate pages for better navigation:

Access settings at /dashboard/admin/settings/:

General Settings (/settings/general)

Site title, description, and branding
Logo upload and domain configuration
Basic site information

Layout Settings (/settings/layout)

Page layouts and card styles
Visual structure and organization
Display preferences

Theme Settings (/settings/themes)

Color schemes and visual themes
Font selections and styling
Dark/light mode configuration

Feature Settings (/settings/features)

Monetization toggles (advertising, paid submissions)
AI features (URL scanning, content analysis)
Integration settings (external services)

SEO Settings (/settings/seo)

Search engine optimization
Meta tags and structured data
Analytics configuration

Social Media Settings (/settings/social)

Social media links and profiles
External platform integrations
Social sharing configuration

Monetization Dashboard

Access comprehensive monetization controls at /dashboard/admin/monetization:

Product Management

Sync from Polar - Import all products automatically
Feature Type Assignment - Map products to directory features
Pricing Configuration - Set up pricing tiers
Product Status - Enable/disable products

Revenue Analytics

Featured Product Revenue - Track featured listing income
Submission Revenue - Monitor paid submission earnings
Advertising Revenue - Analyze ad campaign performance
Comprehensive Reports - Monthly/annual revenue tracking

Campaign Management

Ad Campaign Approval - Review and approve advertising campaigns
Submission Queue - Manage paid submission processing
Customer Management - Handle customer inquiries and support

Polar Configuration

NEW Token System:

Separate environments - Production and sandbox tokens
Database-controlled switching - No redeployment needed
Single webhook secret - Shared between environments
Immediate switching - Toggle environments via admin dashboard

Configuration Status:

Token Validation - Check token validity for current environment
Webhook Status - Monitor webhook endpoint health
Environment Indicator - Clear indication of current mode

Database Schema

Enhanced Tables

PolarProduct

model PolarProduct {
  id           String   @id @default(cuid())
  polarId      String   @unique
  name         String
  description  String?
  price        Int      // cents
  currency     String   @default("usd")
  featureType  String   @default("unused")
  isActive     Boolean  @default(true)
  slug         String   @unique
  createdAt    DateTime @default(now())
  updatedAt    DateTime @updatedAt
}

AdCampaign

model AdCampaign {
  id          String   @id @default(cuid())
  title       String
  url         String
  imageUrl    String
  placement   String
  status      String   @default("pending")
  userId      String
  orderId     String?
  startDate   DateTime?
  endDate     DateTime?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
  
  user        User     @relation(fields: [userId], references: [id])
}

PaidSubmission

model PaidSubmission {
  id             String   @id @default(cuid())
  submissionType String   // 'express' | 'premium'
  productTitle   String
  productUrl     String
  status         String   @default("pending")
  userId         String
  orderId        String?
  processedAt    DateTime?
  createdAt      DateTime @default(now())
  updatedAt      DateTime @updatedAt
  
  user           User     @relation(fields: [userId], references: [id])
}

API Endpoints

Paid Submissions

POST /api/submit-paid

Handle submission with payment processing
Create checkout session for selected tier
Process webhook for successful payments

GET /api/admin/submissions

Admin submission management
Filter by status and submission type
Bulk processing capabilities

Advertising

POST /api/ads/checkout

Create ad campaign checkout session
Validate campaign data and placement availability
Process payment and create pending campaign

GET /api/ads/placements

Get available ad placements
Check capacity and availability
Return placement pricing

PATCH /api/admin/ads/approve/:id

Approve pending ad campaign
Activate campaign and set live dates
Send approval notifications

Monetization

POST /api/admin/polar-products/sync

Sync products from Polar dashboard
Preserve existing configurations
Handle new product discovery

GET /api/featured/revenue

Featured product revenue analytics
Track revenue by time period
Export revenue reports

GET /api/admin/analytics/revenue

Comprehensive revenue analytics
Multi-stream revenue tracking
Customer lifetime value analysis

Security & Guidelines

Payment Security

PCI Compliance

All payments processed through Polar
No sensitive payment data stored locally
Secure webhook validation with cryptographic signatures

Environment Isolation

Separate production and sandbox environments
Database-controlled environment switching
Secure token management

Content Guidelines

Ad Content Review

Manual approval process for all campaigns
Content guidelines enforcement
Inappropriate content rejection

Submission Quality

Paid submissions still subject to quality guidelines
Enhanced review process for premium tiers
Fast-track processing without compromising quality

Privacy Considerations

Data Collection

Clear disclosure of analytics data collection
Customer consent for marketing communications
GDPR compliance for European users

Customer Information

Secure handling of customer data
Minimal data collection principles
Regular data cleanup and retention policies

Troubleshooting

Common Issues

Sync Problems

Check current environment: Verify production/sandbox mode
Token validation: Ensure tokens are valid for current environment
API connectivity: Test Polar API connection

# Test Polar connection
curl -H "Authorization: Bearer $POLAR_ACCESS_TOKEN_PROD" \
     https://api.polar.sh/v1/products

Webhook Issues

URL accessibility: Verify webhook URL is publicly accessible
Secret validation: Check webhook secret matches environment variable
Event monitoring: Monitor webhook delivery in Polar dashboard

Revenue Discrepancies

Webhook processing: Ensure all webhook events are processed
Failed payments: Check for failed payments or refunds
Currency conversion: Verify currency handling if applicable

Environment Switching

Database settings: Use admin dashboard for environment switching
Token configuration: Ensure both production and sandbox tokens are set
Immediate effect: Changes take effect immediately without redeployment

Debug Tools

Enable comprehensive logging:

DEBUG_POLAR=true
DEBUG_WEBHOOKS=true
DEBUG_REVENUE=true

Performance Monitoring

Monitor key metrics:

Webhook processing time - Payment automation speed
Ad load performance - Site speed impact from ad placements
Revenue accuracy - Financial reconciliation and reporting
Environment switching - Database query performance

Best Practices

Revenue Optimization

Pricing Strategy

A/B test pricing - Experiment with submission tier pricing
Seasonal campaigns - Adjust ad pricing for high-traffic periods
Volume discounts - Incentivize bulk ad purchases

Customer Retention

Loyalty programs - Rewards for repeat advertisers
Subscription models - Recurring revenue opportunities
Customer feedback - Continuous improvement based on user input

User Experience

Clear Pricing

Transparent cost structure - No hidden fees
Value proposition - Clearly communicate benefits
Pricing comparison - Help users choose appropriate tier

Fast Processing

Deliver on promises - Meet stated processing times
Status updates - Keep customers informed of progress
Quality assurance - Maintain high standards across all tiers

Growth Strategies

Package Deals

Bundle features - Combine services for higher value
Cross-selling - Promote complementary services
Upselling - Encourage upgrades to premium tiers

Marketing Integration

Social media promotion - Leverage social channels
Content marketing - Blog about success stories
Email campaigns - Nurture leads and repeat customers

2. Database Migration

pnpm prisma db push

3. Admin Settings Restructure

Access individual settings pages instead of accordion
Configure environment switching via admin dashboard
Update bookmarks to new settings URLs

4. Feature Configuration

Enable advertising in /dashboard/admin/settings/features
Configure paid submission products in monetization dashboard
Test environment switching between sandbox and production

5. Webhook Configuration

Update webhook endpoints if needed
Test webhook delivery for all payment types
Verify webhook secret is properly configured

6. User Communication

Announce new features to existing users
Update terms of service to reflect new monetization options
Provide pricing transparency and migration timeline

Testing Checklist

Before going live:

Both production and sandbox tokens configured
Webhook endpoint accessible and validated
All payment flows tested in sandbox mode
Ad campaign approval workflow tested
Revenue tracking and analytics verified
Environment switching tested
Customer support processes updated
Documentation updated and accessible

Environment Variables Reference

Required Variables

# Production environment
POLAR_ACCESS_TOKEN_PROD=your-production-access-token

# Sandbox environment
POLAR_ACCESS_TOKEN_SANDBOX=your-sandbox-access-token

# Shared webhook secret
POLAR_WEBHOOK_SECRET=your-webhook-secret

Optional Variables

# Debug logging
DEBUG_POLAR=false
DEBUG_WEBHOOKS=false
DEBUG_REVENUE=false

PreviousPayments NextPrivate Pages

Last updated 19 days ago