# Dodo Payments Setup Guide for Plugin Compass

This guide explains how to configure Dodo Payments for the Shopify AI App Builder (Plugin Compass) so users can purchase subscription plans and token top-ups through Dodo Checkout.

## Overview

The app uses **Dodo Checkout Sessions** for:
1. **Subscription Plans**: Monthly/Yearly recurring billing for different service tiers.
2. **Token Top-ups**: One-time purchases of AI credits with automatic plan-based discounts.

---

## 1) Create a Dodo Payments account

1. Sign up: https://dodopayments.com
2. Complete your business verification.
3. In the dashboard, navigate to **Developer → API Keys** and generate **Test** and **Live** keys.

---

## 2) Create subscription products in Dodo

Create **18 subscription products** in **Products** (3 plans × 2 billing cycles × 3 currencies):

### Starter Plan ($7.50/mo, $75/year)
- Currencies: USD, GBP, EUR
- Billing: Monthly, Yearly (Recurring)

### Professional Plan ($25/mo, $250/year)
- Currencies: USD, GBP, EUR
- Billing: Monthly, Yearly (Recurring)

### Enterprise Plan ($75/mo, $750/year)
- Currencies: USD, GBP, EUR
- Billing: Monthly, Yearly (Recurring)

**Important**: Enable **Recurring Billing** on each subscription product and set the interval (1 month or 12 months).

---

## 3) Create token top-up products in Dodo

Create **15 one-time payment products** for token top-ups (5 options × 3 currencies). These products are shared across all plans, and discounts are applied automatically at checkout based on the user's subscription plan.

### Top-up Options
1. **Option 1**: 100,000 tokens
2. **Option 2**: 500,000 tokens
3. **Option 3**: 1,000,000 tokens
4. **Option 4**: 5,000,000 tokens
5. **Option 5**: 10,000,000 tokens

### Currencies
For each option, create 3 separate products with different currencies:
- **USD** (United States Dollar)
- **EUR** (Euro) - priced same as USD (1:1 ratio)
- **GBP** (British Pound) - priced ~15% lower than USD

### Recommended Pricing
The following pricing is already configured in the application (in cents/minor units):

| Option | Tokens | USD Price | EUR Price | GBP Price |
|---------|---------|------------|------------|------------|
| 1 | 100,000 | $7.50 | €7.50 | £6.25 |
| 2 | 500,000 | $35.00 | €35.00 | £29.50 |
| 3 | 1,000,000 | $65.00 | €65.00 | £54.50 |
| 4 | 5,000,000 | $250.00 | €250.00 | £210.00 |
| 5 | 10,000,000 | $450.00 | €450.00 | £375.00 |

---

## 4) Environment Variables Reference (Dodo Specific)

Add these variables to your deployment (Docker, Portainer, or `.env`).

### Core Dodo Configuration
- `DODO_PAYMENTS_API_KEY`: Your Dodo API key (starts with `dp_test_` or `dp_live_`).
- `DODO_PAYMENTS_ENV`: Set to `test` or `live`.
- `DODO_PAYMENTS_WEBHOOK_KEY`: Optional secret for validating Dodo webhooks.
- `DODO_MIN_AMOUNT`: Minimum charge in cents after discounts (default: 50). Top-ups will never cost less than this.

### Subscription Product IDs
Map each plan/cycle/currency to its Dodo Product ID from the dashboard:
- `DODO_STARTER_MONTHLY_USD`, `DODO_STARTER_YEARLY_USD`, etc.
- `DODO_PROFESSIONAL_MONTHLY_USD`, `DODO_PROFESSIONAL_YEARLY_USD`, etc.
- `DODO_ENTERPRISE_MONTHLY_USD`, `DODO_ENTERPRISE_YEARLY_USD`, etc.

### Subscription Pricing (Display & Validation)
Amounts in minor units (e.g., 750 for $7.50, 2500 for $25.00):
- `DODO_STARTER_MONTHLY_USD_AMOUNT`, `DODO_STARTER_YEARLY_USD_AMOUNT`, etc.
- `DODO_PROFESSIONAL_MONTHLY_USD_AMOUNT`, etc.
- `DODO_ENTERPRISE_MONTHLY_USD_AMOUNT`, etc.

### Token Top-up Configuration (4 Options × 3 Currencies)
- **Product IDs** (map to Dodo dashboard products):
  - `DODO_TOPUP_1_USD`, `DODO_TOPUP_1_GBP`, `DODO_TOPUP_1_EUR`
  - `DODO_TOPUP_2_USD`, `DODO_TOPUP_2_GBP`, `DODO_TOPUP_2_EUR`
  - `DODO_TOPUP_3_USD`, `DODO_TOPUP_3_GBP`, `DODO_TOPUP_3_EUR`
  - `DODO_TOPUP_4_USD`, `DODO_TOPUP_4_GBP`, `DODO_TOPUP_4_EUR`
- **Token Amounts** (credits granted per option):
  - `DODO_TOPUP_TOKENS_1`: Number of tokens for Option 1 (default: 100,000)
  - `DODO_TOPUP_TOKENS_2`: Number of tokens for Option 2 (default: 5,000,000)
  - `DODO_TOPUP_TOKENS_3`: Number of tokens for Option 3 (default: 20,000,000)
  - `DODO_TOPUP_TOKENS_4`: Number of tokens for Option 4 (default: 50,000,000)
- **Pricing** (in cents/minor units, optional validation):
  - `DODO_TOPUP_1_USD_AMOUNT`, `DODO_TOPUP_1_GBP_AMOUNT`, `DODO_TOPUP_1_EUR_AMOUNT`
  - `DODO_TOPUP_2_USD_AMOUNT`, `DODO_TOPUP_2_GBP_AMOUNT`, `DODO_TOPUP_2_EUR_AMOUNT`
  - `DODO_TOPUP_3_USD_AMOUNT`, `DODO_TOPUP_3_GBP_AMOUNT`, `DODO_TOPUP_3_EUR_AMOUNT`
  - `DODO_TOPUP_4_USD_AMOUNT`, `DODO_TOPUP_4_GBP_AMOUNT`, `DODO_TOPUP_4_EUR_AMOUNT`

### Automatic Plan Discounts for Top-ups
The following discounts are automatically applied to the base price of any top-up product:
- **Professional Plan**: 2.5% discount.
- **Enterprise Plan**: 5% discount.
- **Hobby & Starter Plans**: Standard price (0% discount).

---

## 5) Full Environment Variable Reference

### Core Server Settings
- `CHAT_PORT`: Port the server listens on (default: 4000).
- `CHAT_HOST`: Host interface to bind to (default: 0.0.0.0).
- `SESSION_SECRET`: **CRITICAL**. Random string for cookie encryption. Use `openssl rand -hex 32`.
- `ADMIN_USER` / `ADMIN_PASSWORD`: Credentials for the `/admin` management dashboard.
- `PUBLIC_BASE_URL`: The public URL of your app (e.g., `https://plugincompass.ai`), used for redirects and emails.
- `MAX_JSON_BODY_SIZE`: Max size for JSON payloads in bytes (default: 6,000,000).
- `MAX_ATTACHMENT_SIZE`: Max size per file attachment in bytes (default: 5,000,000).

### LLM Providers & AI
- `OPENROUTER_API_KEY`: Key for OpenRouter (primary planning provider).
- `MISTRAL_API_KEY`: Key for Mistral AI (alternative provider).
- `GROQ_API_KEY`, `GOOGLE_API_KEY`, `NVIDIA_API_KEY`: Optional direct keys for these providers.
- `OPENCODE_API_KEY`: Optional key for specific OpenCode models.

### Email (SMTP)
- `SMTP_HOST`: Hostname of your SMTP server (e.g., `smtp.gmail.com`).
- `SMTP_PORT`: SMTP port (default: 587).
- `SMTP_USER` / `SMTP_PASS`: SMTP credentials.
- `SMTP_FROM`: Sender email address.

### Analytics & Security
- `POSTHOG_API_KEY`: Your PostHog project API key.
- `COOKIE_SECURE`: Set to `1` for HTTPS-only cookies (recommended for production).
- `API_RATE_LIMIT`: Max API requests per minute per user (default: 100).
- `ENABLE_CAPTCHA`: Set to `1` to enable hCaptcha on login.
- `HCAPTCHA_SITE_KEY` / `HCAPTCHA_SECRET_KEY`: hCaptcha credentials.

### Resource & Performance (Docker)
- `CONTAINER_MEMORY_LIMIT`: Assumed memory available to the app (e.g., `512M`).
- `CONTAINER_CPU_LIMIT`: Assumed CPU cores available (e.g., `0.5`).
- `OPENCODE_MAX_CONCURRENCY`: Limit on simultaneous AI build processes (0 = unlimited).

---

## 6) Testing the Payment Flow

1. **Sign in** and visit `/select-plan`.
2. **Choose a plan** and complete checkout in Dodo Test Mode.
3. **Verify subscription** status in `/settings`.
4. **Visit `/topup`** and select a token pack.
5. **Check discount**: Verify that the price correctly reflects your plan's discount (if applicable).
6. **Confirm credits**: After payment, verify your token balance increases in the builder or settings.

## 7) Configure Pay-As-You-Go (Overage) Billing

Paid plans can now exceed their monthly token limits. Any overage is billed at **£2.00 / $2.50 / €2.50 per 1,000,000 tokens** by default.

**Create 3 PAYG products (one per currency)**
- Price them at the rates above for 1,000,000 tokens.
- Map the product IDs via environment variables: `DODO_PAYG_USD`, `DODO_PAYG_GBP`, `DODO_PAYG_EUR`.

**Configure pricing and behavior (env vars)**
- `DODO_PAYG_USD_AMOUNT`, `DODO_PAYG_GBP_AMOUNT`, `DODO_PAYG_EUR_AMOUNT`: Override price per PAYG unit (minor units). Defaults: 250 / 200 / 250.
- `DODO_PAYG_UNIT_TOKENS`: Tokens per PAYG unit (default: 1,000,000).
- `DODO_PAYG_MIN_TOKENS`: Optional minimum overage before creating a checkout (default: 0).
- `DODO_PAYG_ENABLED`: Set to `0` to disable PAYG overage billing (default: enabled).

**Operational flow**
- When a paid user exceeds their plan limit, usage keeps flowing and the overage is tracked for the current month.
- Use `/api/payg/status` to fetch outstanding overage and currency.
- Call `/api/payg/checkout` to create a Dodo Checkout for the owed amount (return URL defaults to `/settings`).
- Call `/api/payg/confirm?session_id=...` after payment to mark the charge as paid and clear the outstanding balance for that month.

Reference: [Dodo Payments API Documentation](https://docs.dodopayments.com)
