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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.directoryfa.st/features/monetization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.