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:
  • Response: { "checkoutUrl": "https://checkout.dodopayments.com/..." }
  • Idempotency: optional Idempotency-Key supported for 10 minutes after a successful response. Retrying the same key with an identical body replays the original checkout response instead of creating another checkout attempt.
  • 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": "..." }
  • Idempotency: optional Idempotency-Key supported. Retrying the same key replays the original portal response instead of creating another portal attempt.

​
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, api_business, enterprise):
Notes:
  • Price fields are flat on the tier. Paid tiers always expose monthlyPrice / monthlyProductId, and add annualPrice / annualProductId only when an annual variant exists — API Business is monthly-only, so those fields are absent on it. 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.
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. affonso_referral is the vendor-contracted metadata key Dodo forwards to Affonso’s referral-tracking webhook. The key name is load-bearing — renaming it (to wm_referral, ref, etc.) silently breaks Dodo→Affonso attribution. See convex/payments/checkout.ts and convex/payments/subscriptionHelpers.ts for the writer/reader call sites.

​
Waitlist

​
POST /api/leads/v1/register-interest

Captures an email into the Convex waitlist table. Turnstile-verified (desktop sources bypass), rate-limited per IP. Part of LeadsService; see Platform endpoints for the request shape.