185 lines
8.3 KiB
Markdown
185 lines
8.3 KiB
Markdown
# 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)
|