# Monetization

## 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**

   ```bash
   # 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
   ```
2. **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
3. **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
4. **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

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

#### Implementation

```typescript
// 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

```typescript
// 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

1. **Create Featured Product** in Polar dashboard
2. **Assign `featured` feature type** in monetization settings
3. **Configure pricing** and duration
4. **Enable feature** in admin settings

#### Implementation

```typescript
// 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**

```sql
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**

```sql
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**

```sql
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

```bash
# 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:

```bash
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**

```bash
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

```bash
# 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

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