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:

  1. 🚀 Paid Submissions - Express and Premium submission tiers

  2. 📺 Advertising Platform - Strategic ad placements throughout your site

  3. ⭐ 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

  1. Configure Polar Integration

    POLAR_ACCESS_TOKEN=your_access_token
POLAR_WEBHOOK_SECRET=your_webhook_secret
POLAR_SERVER=production  # or 'sandbox'

  2. 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

  3. Enable Features

    • Configure advertising in /dashboard/admin/settings

    • Set paid submission preferences

    • Test webhook endpoints

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:

    • Submission status tracking

    • Email notifications

    • Priority support

Premium Submission

  • Processing Time: Same day review

  • Review Type: Immediate priority processing

  • Placement: Featured placement for 7 days

  • Features:

    • All Express features

    • Featured listing boost

    • Social media promotion

    • Dedicated support channel

Configuration

Admin Dashboard Setup

  1. Product Configuration

    Feature Type: express_submission
Polar Product: Your Express product ID
Price: $9.99 (auto-synced from Polar)
Status: Active

  2. Submission Settings

    • Navigate to /dashboard/admin/monetization

    • Configure free submission toggle

    • Monitor submission analytics

    • Review payment tracking

Implementation Example

// Submission form with tier selection
const submissionTiers = [
  {
    id: 'free',
    name: 'Free Submission',
    price: 0,
    features: ['7-14 days processing', 'Standard placement'],
    timeline: '7-14 days'
  },
  {
    id: 'express', 
    name: 'Express Submission',
    price: 9.99,
    features: ['24-48h processing', 'Priority queue'],
    timeline: '24-48 hours'
  },
  {
    id: 'premium',
    name: 'Premium Submission', 
    price: 29.99,
    features: ['Same day review', '7-day featured'],
    timeline: 'Same day'
  }
];

Webhook Processing

Paid submissions are automatically processed via webhooks:

// Automatic paid submission processing
if (metadata.type === 'paid_submission') {
  const suggestion = await prisma.suggestion.create({
    data: {
      title: submissionData.productTitle,
      owner: submissionData.productOwner,
      status: 'pending',
      isPaid: true,
      paymentId: orderId,
      submissionType: metadata.submissionType,
      // Auto-linked to user and category
    }
  });
}

Advertising Platform

Overview

The advertising platform provides strategic ad placements throughout your directory with capacity management and real-time analytics.

Ad Placement Locations

Homepage Hero Ads

  • Location: Top of homepage

  • Format: Compact banner (350x80px)

  • Capacity: Up to 4 ads in grid layout

  • Visibility: Highest traffic area

  • Ideal For: Brand awareness, new product launches

Product Page Sidebar Ads

  • Location: Product detail page sidebar

  • Format: Compact banner (350x80px)

  • Capacity: Up to 4 ads stacked

  • Visibility: High-intent product viewers

  • Ideal For: Related products, competitors

Blog Post Sidebar Ads

  • Location: Blog post content sidebar

  • Format: Compact banner (350x80px)

  • Capacity: Up to 4 ads stacked

  • Visibility: Engaged content readers

  • Ideal For: Thought leadership, educational content

Collection Page Ads

  • Location: Collection browsing pages

  • Format: Compact banner (350x80px)

  • Capacity: Up to 4 ads in grid

  • Visibility: Category-focused users

  • Ideal For: Category-specific targeting

Category Page Ads

  • Location: Category listing pages

  • Format: Compact banner (350x80px)

  • Capacity: Up to 4 ads in grid

  • Visibility: Category browsers

  • Ideal For: Niche market targeting

Pricing Model

Flat-Rate Monthly Pricing - No complex CPC/CPM calculations

  • Simple monthly subscription per placement

  • Predictable costs for advertisers

  • Guaranteed placement duration

  • No click-through requirements

Ad Campaign Workflow

  1. Campaign Creation

    • Advertiser selects placement location

    • Provides ad creative and targeting details

    • Completes Polar checkout process

  2. Admin Approval

    • Campaign enters "PENDING_APPROVAL" status

    • Admin reviews ad content and guidelines

    • Approval activates campaign and starts billing

  3. Active Campaign

    • Ad displays in selected placement

    • Real-time impression and click tracking

    • Automatic campaign management

  4. Analytics & Reporting

    • Campaign performance metrics

    • Revenue tracking per placement

    • Advertiser dashboard access

Implementation Details

Ad Purchase Flow

// Ad campaign purchase process
const adPackages = [
  {
    id: 'homepage-hero',
    name: 'Homepage Hero Ads',
    description: 'Prime placement at the top of homepage',
    price: 299.99,
    placement: 'HOMEPAGE_HERO',
    features: ['4 ad slots', 'Premium visibility', 'Monthly duration']
  }
  // ... other packages
];

const handleAdPurchase = async (packageData, campaignData) => {
  const response = await fetch('/api/ads/checkout', {
    method: 'POST',
    body: JSON.stringify({ packageData, campaignData })
  });
  
  const { checkoutUrl } = await response.json();
  window.location.href = checkoutUrl;
};

Auto-Placement Management

// Automatic ad placement creation
const placement = await prisma.adPlacement.create({
  data: {
    name: placementData.name,
    location: placementData.location,
    dimensions: '350x80',
    maxAdsPerPage: 4,
    priority: 8,
    isActive: true
  }
});

Revenue Tracking

Track advertising revenue with detailed analytics:

  • Revenue by placement - Performance per ad location

  • Campaign profitability - ROI tracking per campaign

  • Occupancy rates - Placement capacity utilization

  • Advertiser retention - Repeat customer analysis

Featured Products

Traditional Featured Listings

Enhanced visibility for existing directory products:

  • 30-day featured placement in special sections

  • Enhanced presentation with visual indicators

  • Priority positioning in search results

  • Homepage feature rotation

Implementation

// Featured product purchase
const createFeatured = async (productSlug: string) => {
  const response = await fetch('/api/checkout/polar', {
    method: 'POST',
    body: JSON.stringify({
      productSlug,
      metadata: { featureType: 'featured' }
    })
  });
  
  const { checkoutUrl } = await response.json();
  window.location.href = checkoutUrl;
};

Auto-Management

Featured products are automatically managed:

  • Automatic expiration after 30 days

  • Renewal notifications before expiration

  • Usage analytics and performance tracking

  • Revenue attribution to featured placements

Admin Dashboard

Monetization Overview

Access comprehensive controls at /dashboard/admin/monetization:

Product Management

  • Polar Product Sync - One-click product import

  • Feature Type Assignment - Map products to features

  • Pricing Management - Auto-sync from Polar

  • Status Control - Activate/deactivate products

Revenue Analytics

  • Total Revenue Tracking - Across all monetization features

  • Monthly/Annual Trends - Growth tracking

  • Feature Performance - Revenue by feature type

  • Customer Metrics - LTV and retention analysis

Campaign Management (Advertising)

  • Active Campaigns - Monitor running ad campaigns

  • Approval Queue - Review pending advertisements

  • Placement Analytics - Performance by ad location

  • Capacity Management - Monitor placement availability

Settings Configuration

Configure monetization features in /dashboard/admin/settings:

Polar Configuration

  • API Credentials - Access token and webhook secret

  • Server Environment - Production vs sandbox

  • Connection Status - Real-time configuration validation

Feature Toggles

  • Advertising System - Global enable/disable

  • Free Submissions - Allow/disallow free tier

  • Feature Announcements - User-facing feature notifications

Database Schema

Core Models

PolarProduct

model PolarProduct {
  id          String   @id @default(cuid())
  productId   String   @unique // Polar product UUID
  name        String
  slug        String   @unique
  featureType String?  // Feature assignment
  price       Float?
  isActive    Boolean  @default(true)
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt
}

Suggestion (Enhanced)

model Suggestion {
  // ... existing fields
  isPaid         Boolean @default(false)
  paymentId      String?
  submissionType String  @default('free')
}

Advertising Models

model AdCampaign {
  id          String @id @default(cuid())
  name        String
  description String?
  status      String // PENDING_PAYMENT, PENDING_APPROVAL, ACTIVE, PAUSED
  startDate   DateTime
  endDate     DateTime
  bidAmount   Float
  totalSpent  Float @default(0)
  userId      String
  ads         Ad[]
}

model Ad {
  id           String @id @default(cuid())
  title        String
  description  String
  imageUrl     String
  clickUrl     String
  status       String // PENDING_PAYMENT, PENDING, APPROVED, ACTIVE, PAUSED
  campaignId   String
  campaign     AdCampaign @relation(fields: [campaignId], references: [id])
  placements   AdPlacement[]
}

model AdPlacement {
  id             String @id @default(cuid())
  name           String
  location       String // HOMEPAGE_HERO, PRODUCT_PAGE_SIDEBAR, etc.
  dimensions     String @default("350x80")
  maxAdsPerPage  Int    @default(4)
  priority       Int    @default(5)
  isActive       Boolean @default(true)
  ads            Ad[]
}

API Endpoints

  • POST /api/submit-paid - Handle submission with payment

  • GET /api/admin/submissions - Admin submission management

Advertising

  • POST /api/ads/checkout - Create ad campaign checkout

  • GET /api/ads/placements - Available ad placements

  • PATCH /api/admin/ads/approve/:id - Approve ad campaign

Monetization

  • POST /api/admin/polar-products/sync - Sync products from Polar

  • GET /api/featured/revenue - Revenue analytics

  • GET /api/admin/analytics/revenue - Comprehensive revenue data

Security & Guidelines

Payment Security

  • PCI Compliance - Handled by Polar

  • Webhook Verification - Cryptographic signature validation

  • Environment Isolation - Separate sandbox/production environments

Content Guidelines

  • Ad Content Review - Manual approval process

  • Submission Quality - Paid submissions still subject to guidelines

  • Refund Policy - Clear terms for service delivery

Privacy Considerations

  • Data Collection - Analytics data collection disclosure

  • Customer Information - Secure handling of payment data

  • GDPR Compliance - User consent and data management

Troubleshooting

Common Issues

Sync Problems

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

Webhook Issues

  • Verify webhook URL is publicly accessible

  • Check webhook secret matches environment variable

  • Monitor webhook delivery in Polar dashboard

Revenue Discrepancies

  • Ensure all webhook events are properly processed

  • Check for failed payments or refunds

  • Verify currency conversion if applicable

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

  • Revenue Accuracy - Financial reconciliation

Best Practices

Revenue Optimization

  • A/B Test Pricing - Experiment with submission tier pricing

  • Seasonal Campaigns - Adjust ad pricing for high-traffic periods

  • Customer Retention - Implement loyalty programs for repeat advertisers

User Experience

  • Clear Pricing - Transparent cost structure

  • Fast Processing - Deliver on promised processing times

  • Quality Control - Maintain high standards for all tiers

Growth Strategies

  • Package Deals - Bundle features for higher value

  • Volume Discounts - Incentivize bulk purchases

  • Referral Programs - Customer acquisition through existing users

Migration Guide

From v1.5.x to v1.6.0

  1. Database Migration

    pnpm prisma db push

  2. Environment Updates

    # Add if missing
DEBUG_POLAR=false

  3. Feature Configuration

    • Enable advertising in admin settings

    • Configure paid submission products

    • Test webhook endpoints

  4. User Communication

    • Announce new monetization features

    • Update terms of service

    • Provide pricing transparency

PreviousPaymentsNextPrivate Pages

Last updated