Files

southseact-3d ed67b7741b Restore to commit 74e578279624c6045ca440a3459ebfa1f8d54191

2026-02-07 20:32:41 +00:00

8.3 KiB

Raw Blame History

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:

Subscription Plans: Monthly/Yearly recurring billing for different service tiers.
Token Top-ups: One-time purchases of AI credits with automatic plan-based discounts.

1) Create a Dodo Payments account

Sign up: https://dodopayments.com
Complete your business verification.
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

Option 1: 100,000 tokens
Option 2: 500,000 tokens
Option 3: 1,000,000 tokens
Option 4: 5,000,000 tokens
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

Sign in and visit /select-plan.
Choose a plan and complete checkout in Dodo Test Mode.
Verify subscription status in /settings.
Visit /topup and select a token pack.
Check discount: Verify that the price correctly reflects your plan's discount (if applicable).
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

8.3 KiB Raw Blame History Unescape Escape