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
- AppSumo "Activate" →
GET /appsumo/redirect?code=swaps the code for the license key (appsumo.com/openid/token/then/license_key/), upsertsappsumo_licenses, and redirects to portal/appsumo/activate?ticket=<signed>(signed withlib/oauthState, 24 h). Failures redirect with?error=deactivated|no_license|oauth_failed. - 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 →) besideSignupPreview; an already-linked license shows Your AppSumo deal is already activated. POST /appsumo/register(AuthController.appSumoRegister): a verifiedweb_owner(no OTP) + a direct company withcompanies.appsumo_license_key; the license getscompany_id,status: 'active';applyDirectTiercreates a lifetime $0subscription_type: 'appsumo'subscription (appsumo_package_id,package_idnull) plus the month's wallet. No $10 signup grant (signup_wallet_grant_pendingcleared, no welcome wallet). Platform-CRM contact taggedappsumo customer. Failure rolls back the user/company and releases the license.- They land on
/setup.AccountTypeStepoffers only I'm an agency when the tier hasallow_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).
| Event | Handling |
|---|---|
purchase, activate | upsert the license |
upgrade, downgrade | AppSumo 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 |
migrate | add-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_accountsis left negative on purpose.AgencySeatLimitLock(inAgencyLayout) 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 423APPSUMO_SEAT_LIMIT; the own account stays open. Paying:GET /agencies/seat-limit/quote,POST /agencies/seat-limit/buy(Stripe Checkout atextra_seat_price× missing seats, else the cheapest one-timesub_accountagency add-on visible to the agency),POST /agencies/seat-limit/confirm. Bought seats are kept inagencies.appsumo_extra_seatsand survive tier changes; checkouts inappsumo_seat_checkouts. - Tier without an agency:
closeAgencypauses clients (companies.appsumo_paused) and setsagencies.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_enabledforced off without Webhook/API access. - No Agent K on any AppSumo account (
blocksAgentK,agentKAllowedmiddleware;/user/meexposescompany.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);_conversionStripeSubscriptionskips AppSumo. - Chatbot, recording and member limits are skipped (the package sets none). BYOK is stored and returned in
appsumo_planbut 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.ArchivedAccountDeletionJobalso cleansappsumo_licenses.
Environment
| Var | Where | Notes |
|---|---|---|
APPSUMO_API_KEY | backend secret.sops.yaml (PROD + DEV) | webhook HMAC key |
APPSUMO_CLIENT_SECRET | backend secret.sops.yaml (PROD + DEV) | OAuth |
APPSUMO_CLIENT_ID | not in flux | hardcoded default 050442601895 |
APPSUMO_REDIRECT_URI | not in flux | default 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.
Related
- Wallet — signup grants (AppSumo gets none)
- Agency overview
- Agency subscriptions