Skip to main content
WorldMonitor uses Dodo Payments for PRO subscriptions and Convex as the source-of-truth for entitlements. These edge endpoints are thin auth proxies — they validate the Clerk JWT, then forward to Convex HTTP actions via RELAY_SHARED_SECRET.

​
Checkout

​
POST /api/create-checkout

Creates a Dodo checkout session and returns the hosted-checkout URL.
  • Auth: Clerk bearer (required)
  • Body: 
    { "productId": "pro-monthly", "returnUrl": "https://www.worldmonitor.app/pro/success" }
  • Response: { "checkoutUrl": "https://checkout.dodopayments.com/..." }
  • returnUrl is validated against an allowlist on the Convex side.

​
POST /api/customer-portal

Creates a Dodo customer-portal session for an existing subscriber (update card, cancel, view invoices).
  • Auth: Clerk bearer + active entitlement
  • Response: { "portalUrl": "..." }

​
Product catalog

​
GET /api/product-catalog

Returns the tier view-model used by the /pro pricing page. Cached in Redis under product-catalog:v2 for 1 hour; on cache miss, fetches live prices from Dodo Payments and falls back to _product-fallback-prices.js if Dodo is unreachable. Response carries an X-Product-Catalog-Source header so probes can tell cache hits from live fetches. Response (tiers ordered free, pro, api_starter, enterprise): 
{
  "tiers": [
    {
      "name": "Free",
      "description": "Get started with the essentials",
      "features": ["Core dashboard panels", "..."],
      "cta": "Get Started",
      "href": "https://worldmonitor.app",
      "highlighted": false,
      "price": 0,
      "period": "forever"
    },
    {
      "name": "Pro",
      "description": "Full intelligence dashboard",
      "features": ["..."],
      "highlighted": true,
      "monthlyPrice": 20,
      "monthlyProductId": "pdt_0Nbtt71uObulf7fGXhQup",
      "annualPrice": 180,
      "annualProductId": "pdt_0NbttMIfjLWC10jHQWYgJ"
    },
    {
      "name": "API",
      "description": "Programmatic access to intelligence data",
      "features": ["..."],
      "highlighted": false,
      "monthlyPrice": 99,
      "monthlyProductId": "pdt_0NbttVmG1SERrxhygbbUq",
      "annualPrice": 990,
      "annualProductId": "pdt_0Nbu2lawHYE3dv2THgSEV"
    },
    {
      "name": "Enterprise",
      "description": "Custom solutions for organizations",
      "features": ["..."],
      "cta": "Contact Sales",
      "href": "mailto:[email protected]",
      "highlighted": false,
      "price": null
    }
  ],
  "fetchedAt": "2026-04-19T12:00:00Z",
  "cachedUntil": "2026-04-19T13:00:00Z",
  "priceSource": "dodo"
}
Notes:
  • Price fields are flat on the tier. Paid tiers expose monthlyPrice / monthlyProductId and annualPrice / annualProductId. Free uses price: 0, period: "forever"; Enterprise uses price: null.
  • Prices are dollars (Dodo returns cents; the handler divides by 100). Currency is implicit USD for the published catalog.

​
DELETE /api/product-catalog

Purges the cached catalog. Requires Authorization: Bearer $RELAY_SHARED_SECRET. Internal.

​
Referrals

​
GET /api/referral/me

Returns the caller’s deterministic referral code (an 8-char HMAC of the Clerk userId, stable for the life of the account) and a pre-built share URL. Clerk bearer required. The handler also fires a best-effort ctx.waitUntil Convex binding so future /pro?ref=<code> signups can attribute — this never blocks the response. 
{
  "code": "a1b2c3d4",
  "shareUrl": "https://worldmonitor.app/pro?ref=a1b2c3d4"
}
Errors:
  • 401 UNAUTHENTICATED — missing or invalid Clerk JWT.
  • 503 service_unavailable — BRIEF_URL_SIGNING_SECRET not configured (the referral-code HMAC reuses that secret).
No referrals count or rewardMonths is returned today — Dodo’s affonso_referral attribution doesn’t yet flow into Convex, and exposing only the waitlist-side count would mislead.

​
Waitlist

​
POST /api/register-interest

Captures an email into the Convex waitlist table. Turnstile-verified, rate-limited per IP. See Platform endpoints for the request shape.