Skip to main content

AppSumo Licensing

Audience: Engineering · Support · Finance · Where in app: /appsumo/activate (buyer), profile-menu AppSumo plan badge, Super Admin → Packages & billing → AppSumo Packages · Since: 2026-10-25

AppSumo buyers get a lifetime, card-free plan. Their tier maps to an appsumo_packages row that sets a monthly wallet allowance and, for agency tiers, sub-account seats. Code: backend/app/services/AppSumoService.js, controllers/AppSumoController.js, config app/configs/appsumo.js; frontend views/auth/AppSumoActivateView.vue, components/AppSumoPlanBadge.vue, components/agency/AgencySeatLimitLock.vue, components/AppSumoAgencyOfferModal.vue.

Activation flow​

  1. AppSumo "Activate" → GET /appsumo/redirect?code= swaps the code for the license key (appsumo.com/openid/token/ then /license_key/), upserts appsumo_licenses, and redirects to portal /appsumo/activate?ticket=<signed> (signed with lib/oauthState, 24 h). Failures redirect with ?error=deactivated|no_license|oauth_failed.
  2. The page reads the ticket (GET /appsumo/ticket/:ticket) and shows Activate your AppSumo deal (Your name / Business name / Work email / Password, Activate and create account →) beside SignupPreview; an already-linked license shows Your AppSumo deal is already activated.
  3. POST /appsumo/register (AuthController.appSumoRegister): a verified web_owner (no OTP) + a direct company with companies.appsumo_license_key; the license gets company_id, status: 'active'; applyDirectTier creates a lifetime $0 subscription_type: 'appsumo' subscription (appsumo_package_id, package_id null) plus the month's wallet. No $10 signup grant (signup_wallet_grant_pending cleared, no welcome wallet). Platform-CRM contact tagged appsumo customer. Failure rolls back the user/company and releases the license.
  4. They land on /setup. AccountTypeStep offers only I'm an agency when the tier has allow_agency, only My own business otherwise. Agency → POST /agencies/self-serve → AppSumoService.attachAgency: the direct plan ends, the month's direct wallet is taken back, the agency gets the plan, seats and wallet. The business becomes the agency's own site and uses one seat; its $5 own-site balance is moved out of the agency wallet (agency_self_account_signup_transfer, skipped when the wallet is short). No $20 agency grant.

Commit 8850f27c ("activation lands in the agency portal") was superseded by 72e7a92f + the /setup flow.

Tier packages (appsumo_packages)​

One active package per tier, edited at /admin/appsumo-packages (create/edit, no delete; GET/POST /appsumo-packages, GET/PUT /appsumo-packages/:id, super-admin). Form: Package Name, AppSumo Tier, Price ($, display only), Monthly AI Wallet ($) (monthly_wallet_credits, $1 = 100), Sub Accounts, Extra sub-account price ($) (extra_seat_price), checkboxes Allow agency / BYOK / White label / Custom domain / Webhook/API access, Status, Sort Order. Tier count and amounts live only in the DB — query prod before quoting.

APPSUMO_TIER_PACKAGES / tier_packages in the config is dead (hardcoded package ids, unused).

Monthly wallet​

AppSumoWalletJob (schedular, cron 5 0 1 * * — 00:05 UTC on the 1st; idempotent per month; also paid at activation):

  • Agency tier → agency wallet via grantPlanWallet; last month's unused allowance expires.
  • Direct tier → company wallet (remaining_purchased_ai_credits), rolls over.
  • A tier without an agency pays into the own account.

Ledger sources appsumo_wallet* / appsumo_plan_wallet*; labels "AppSumo monthly wallet", "AppSumo wallet moved to your agency", "AppSumo downgrade", "AppSumo downgrade · unused wallet expired", "AppSumo plan ended · wallet expired".

Webhook (POST /appsumo/webhook)​

X-Appsumo-Signature = HMAC-SHA256(X-Appsumo-Timestamp + raw body) keyed with APPSUMO_API_KEY, timing-safe compare (raw body captured for JSON and form bodies in hooks.js). test: true → 200 without touching data; bad signature → 401; processing error → 500 so AppSumo retries. Every event is appended to license.events (last 50).

EventHandling
purchase, activateupsert the license
upgrade, downgradeAppSumo issues a new key: user/agency/company carry over from prev_license_key, the old key gets replaced_by, the tier is re-applied immediately. Downgrade expires the higher tier's leftover allowance; a direct customer's wallet moves by the difference, never below $0
deactivate (refund)direct: appsumo subscription inactive; agency: subscription inactive, every account's expiry = now, plan wallet expires. Skipped when the key was replaced or the reason is an upgrade/downgrade
migrateadd-ons

Tier notifications (cbfdbc0a0): one SYSTEM bell notification to the own account's owner (webhook retries deduped) — "Your AppSumo Tier N plan is active" / "You're now on AppSumo Tier N" / "Your AppSumo plan changed to Tier N", message "Plan: <package>. You can see your tier any time in your profile menu." A direct buyer moving to a tier with allow_agency also gets "Your AppSumo plan now includes an agency account" with Convert to agency account, and a one-time-per-tier popup (AppSumoAgencyOfferModal, Convert to agency account / Not now).

d838e6d64: a business that moved to another subscription is never given a second active AppSumo plan.

Downgrades: seat lock and closed agency​

  • Seat lock: after a downgrade available_sub_accounts is left negative on purpose. AgencySeatLimitLock (in AgencyLayout) shows an un-closable modal "You have more sub-accounts than your plan allows" with Archive sub-accounts and Pay $Y with Stripe; Companies / Add-ons / Payment pages show a bar instead. Server side, opening a client returns 423 APPSUMO_SEAT_LIMIT; the own account stays open. Paying: GET /agencies/seat-limit/quote, POST /agencies/seat-limit/buy (Stripe Checkout at extra_seat_price × missing seats, else the cheapest one-time sub_account agency add-on visible to the agency), POST /agencies/seat-limit/confirm. Bought seats are kept in agencies.appsumo_extra_seats and survive tier changes; checkouts in appsumo_seat_checkouts.
  • Tier without an agency: closeAgency pauses clients (companies.appsumo_paused) and sets agencies.appsumo_no_agency. Modal "Your plan no longer includes an agency" (Log out / Open my business account); agency login refused ("Your AppSumo plan doesn't include an agency account…"). An upgrade reopens the agency and resumes clients.

Caps (AppSumoService.agencyCaps / enforceAgencyCaps)​

Run on tier apply, client-package sync and sub-account create:

  • White label off unless the tier allows it → APPSUMO_NO_WHITE_LABEL; custom domain → APPSUMO_NO_CUSTOM_DOMAIN; webhooks_enabled forced off without Webhook/API access.
  • No Agent K on any AppSumo account (blocksAgentK, agentKAllowed middleware; /user/me exposes company.agent_k_blocked, which hides the Agent K card, setup route, onboarding pick and dashboard nudge).
  • No agency on a business-only tier.
  • In-app plan changes refused ("Your plan is an AppSumo lifetime deal — upgrade or change it on AppSumo."). Convert to Agency Account hidden (useAgencySelfConvert: !company.appsumo_plan); _conversionStripeSubscription skips AppSumo.
  • Chatbot, recording and member limits are skipped (the package sets none). BYOK is stored and returned in appsumo_plan but enforced nowhere.
  • The UI doesn't hide the white-label / custom-domain / webhook toggles — only the server refuses.

company.appsumo_plan (from /user/me) drives the amber AppSumo plan · Tier N badge in the profile popover of both sidebars.

Repair tool​

POST /appsumo/admin/repair-agencies (super-admin, body apply, agency_id, company_id; dry run unless apply): repairAgencyTiers re-applies plan, seats, wallet and lifetime expiry; repairDirectWallets sets up a missing direct plan or pays a missed month (skips customers who moved to another plan). No admin UI and it runs inside the request — not the async job + MigrationPanel pattern. backend/scripts/appsumo-repair-agencies.js is the local-dev twin (its header still describes the old Agency-Package model).

Data model​

  • appsumo_licenses: license_key, prev_license_key, replaced_by, parent_license_key, tier, status (inactive/active/deactivated), user_id, agency_id, company_id, events[]. No admin lookup screen — key → company is DB only.
  • appsumo_packages (above).
  • subscriptions.appsumo_package_id, agency_subscriptions.appsumo_package_id, subscription_type: 'appsumo'.
  • companies.appsumo_license_key, companies.appsumo_paused; agencies.appsumo_extra_seats, appsumo_no_agency, appsumo_seat_checkouts.
  • ArchivedAccountDeletionJob also cleans appsumo_licenses.

Environment​

VarWhereNotes
APPSUMO_API_KEYbackend secret.sops.yaml (PROD + DEV)webhook HMAC key
APPSUMO_CLIENT_SECRETbackend secret.sops.yaml (PROD + DEV)OAuth
APPSUMO_CLIENT_IDnot in fluxhardcoded default 050442601895
APPSUMO_REDIRECT_URInot in fluxdefault https://api.knock-knockapp.com/appsumo/redirect
APPSUMO_VERIFY_SIGNATURE—forced on in production

The schedular needs none of them (the wallet job only reads the DB).

Tests: 8 test/appsumo-*.spec.js specs, all required from test/index.test.js.