Subscriptions
Audience: Sales / Management / Agency-success / Support · Where in app: /agency/subscription-management (overview, plans, addons, history, payment-method) and /agency/subscriptions (per-client list/detail) · Plan availability: Agency tier; payment actions gated by agency.subscription_payments
There are two billing relationships in the agency portal, and this page covers both:
- The agency → Knock Knock. The agency subscribes to an agency package (
AgencyPackageModel) which grants a number of sub-account slots. Stripe bills the agency owner. This is the "Subscription Management" unified screen. - The client → the agency. Each client company has its own
SubscriptionModelpointing at an agency-defined client package. The agency controls these; the client can't self-serve. This is the per-client "Subscriptions" list/detail.
What it does
- Subscription Management (unified, tabbed): Overview, Plans, Add-ons, Payment History, Payment Method.
- Subscribe / change the agency package, with immediate upgrades and deferred downgrades.
- Buy agency add-ons (extra sub-accounts), one-time or recurring.
- View payment history / invoices and manage the payment method.
- Per-client subscriptions list with company + status filters, and a detail view.
- Cancel / reactivate the agency subscription and individual client subscriptions.
How it works
Agency subscription (AgencySubscriptionModel)
One agency subscription row per agency holds package_id (current paid plan), optional new_package_id (a scheduled downgrade), stripe_id, status (active / inactive / canceled), expiry_date, is_trial, and canceled_at / cancel_reason. Subscribing or upgrading creates/updates the Stripe subscription immediately and refreshes total_sub_accounts.
Deferred downgrade is the key behavior: when the agency changes to a cheaper plan (changePackage, POST /agencies/change-package), the change is not applied immediately. Instead:
- Stripe schedules the price change at period end (
scheduleSubscriptionPriceChangeAtPeriodEnd). - Locally,
new_package_idis set;package_idstays on the plan the agency already paid for. - The renewal webhook applies the downgrade (swaps
package_id, recalculates sub-account counts) when the cycle rolls over. - The agency keeps current capacity until then, and gets a "Your plan will change to X on
<date>" response + a downgrade email.
Upgrades (more expensive plan) are charged immediately via Stripe updateSubscription (or, during trial, the trial is canceled and a fresh paid subscription starts).
Per-client subscription (SubscriptionModel)
Each sub-account's subscription is created when the agency provisions/assigns a package. Its expiry_date is derived from the agency's own subscription expiry; remaining_ai_credits comes from the client package. Exception (08315c59c, lib/agencyClientBilling.js): unconverted trial seats (agency_trial_seat: true, agency_trial_converted_at: null) are excluded from clientsRidingAgencySubscription, so an agency renewal / trial extension (StripeController, AppSumoService) no longer pushes their expiry; non-Connect trial clients are seeded with now + trial_days, is_trial: true instead of the agency's expiry. The agency cancels/reactivates these via the company endpoints (see Managing Companies).
Source: frontend/src/views/agency/SubscriptionManagement.vue + frontend/src/components/agency/subscription/*, frontend/src/views/agency/subscriptions/{List,Detail}.vue, and AgencyController.
Configuration & options
Subscription Management tabs
| Tab | Route name | Component | Purpose |
|---|---|---|---|
| Overview | agency-subscription-overview | SubscriptionOverview.vue | Current plan, trial banner/progress, capacity |
| Plans | agency-subscription-plans | SubscriptionPlans.vue | Subscribe / change agency package |
| Add-ons | agency-subscription-addons | SubscriptionAddons.vue | Buy agency add-ons; subscribed list groups identical add-ons with a quantity ("Cancel one"), footer "Using X of Y sub-accounts, including your plan's" + monthly total (a36c1fbb) |
| Wallet | agency-subscription-wallet | AgencyWallet.vue | Agency wallet: transactions ledger, Transfer credits to sub-accounts/playgrounds, auto-recharge |
| Payment History | agency-subscription-history | PaymentHistory.vue | Invoices |
| Payment Method | agency-subscription-payment | PaymentMethodManager.vue | Manage card |
Legacy redirects: /agency/buy-sub-account → Plans, /agency/subscription → Overview, /agency/invoices → Payment History.
Catalog visibility and purchase gate
08627d9ab, frontend a51635e5.
Super-admin only, on Admin → Agencies → Edit and Admin → Agency Invites → Edit (shared card components/admin/AgencyOfferingFields.vue, "Packages & Addons"). Fields on AgencyModel and AgencyInviteModel (copied onto the agency at invite signup): include_public_packages (default false), include_public_addons (default true), plus the agency_packages / agency_addons id lists. Three radio modes per column:
| Mode | UI | Stored as |
|---|---|---|
public | "All public packages/addons" | empty list |
mixed | "All public + private ones I pick" | list + include flag |
selected | "Only ones I pick" | list, flag off |
Rule (lib/agencyCatalogVisibility.js): empty list → public items only (package_type: 'public' / addon visibility: 'public'); list + flag → public plus listed; list without flag → only listed. Legacy semantics survive through the defaults (an assigned package list replaces public packages; assigned add-ons add to them). Inactive items are never shown.
Purchase gate: every agency purchase path — subscribe, subscribe-calculations, package-change-calculations, changePackage, buyAddon, the auto-recharge add-on pick and the AppSumo extra-seat price — resolves the id through _agencyCatalogItem (status: 'active' + the visibility rule), so a hidden or inactive id can't be bought via the API (400/404). Side effect: an agency on a package later retired or hidden can't re-subscribe or run calculations against it.
Agency subscription actions (repository → endpoint)
| Action | Repository fn | Endpoint | Notes |
|---|---|---|---|
| Subscribe | subscribeAgency({ package_id, trial }) | POST /agencies/subscribe | Wrapped with Rewardful affiliate data |
| First-time price calc | getSubscribeCalculations(packageId) | POST /agencies/subscribe-calculations | Returns { monthly_price, gst, total_due, currency } |
| Change plan | changeAgencyPackage({ package_id }) | POST /agencies/change-package | Immediate upgrade / deferred downgrade |
| Change calc (proration) | getPackageChangeCalculations(packageId) | POST /agencies/package-change-calculations | Prorated amounts |
| Buy agency add-on | buyAgencyAddon(addonId) | POST /agencies/addon | Extra sub-accounts (one-time or recurring) |
| Cancel agency sub | cancelAgencySubscription({ reason }) | POST /agencies/unsubscribe | Stores cancel_reason |
| Reactivate | reactivateAgencySubscription(subId) | POST /agencies/reactivate-subscription | — |
| Retry failed payment | retryAgencyPayment(subId) | POST /subscription/stripe-payment-retry/:id | — |
| Invoices | getInvoices() | GET /agency/invoices | — |
| AI credit usage | getCreditUsage() | GET /agency/credit-usage | Pooled credit history |
All payment/plan actions require agency.subscription_payments (owner always passes); changePackage returns 403 otherwise.
Per-client subscriptions (subscriptions/List.vue, Detail.vue)
| Control | Repository fn | Endpoint |
|---|---|---|
| List (filter by company + status) | getSubscriptions({ companyId, status, page, pageSize }) | GET /agency/subscriptions |
| Detail | getSubscriptionById(id) | GET /agency/subscriptions/:id |
| Active sub by user | getActiveSubscriptionByUserId(userId) | GET /subscription/active/:userId |
| Cancel client sub | cancelCompanySubscription(companyId) | POST /agencies/companies/:id/cancel-subscription |
| Reactivate client sub | reactivateCompanySubscription(companyId) | POST /agencies/companies/:id/reactivate-subscription |
Status filter values: active, cancelled, expired (UI badge colors map active→green, cancelled→red, expired→gray).
Agency package model fields (AgencyPackageModel)
| Field | Notes |
|---|---|
name, description | Plan identity |
amount, currency (default usd) | Price the agency pays |
sub_accounts | Slot capacity granted |
trial | Whether the plan offers a trial |
stripe_product_id, stripe_price_id | Stripe linkage |
status (active/inactive), package_type (private/public), sort_order | Catalog control |
Agency add-on model fields (AgencyAddonModel)
| Field | Notes |
|---|---|
amount, currency, type (sub_account) | What the add-on grants/costs |
billing_type (one_time / recurring, default recurring) | One-time charge vs. rebills each cycle |
visibility (private/public), status, sort_order | Catalog control |
Behaviors & edge cases
- Deferred downgrade keeps capacity. Until the cycle ends the agency stays on the paid plan;
new_package_idflags the pending change. A downgrade is blocked during trial and blocked if it can't hold the in-use sub-accounts (returns a message telling the agency to remove sub-accounts first). - Upgrades are immediate; trial upgrades cancel the trial and start a fresh paid subscription.
- Billing responsibility split. Stripe bills the agency for the agency package + add-ons. Clients are billed by the agency — off-platform, or through the agency's own Stripe account via Connect (priced packages; see Client Billing). Client
SubscriptionModelrows track entitlement/expiry; for Connect-billed clients the Connect webhook drives them, otherwise they ride the agency's expiry. - Trial banner. Overview shows an amber "Trial Active" (with progress bar) or red "Trial Expired" state driven by
subscription.is_trial+expiry_date. - Client lock after the agency lapses. Client
expiry_date= agency period end + 30 min; the frontend grace window for agency clients is 3 hours (direct customers keep 7 days —store/app.jsgraceEnd,3777038c). After it, owners and members alike land oninform-agency("Subscription Expired", agency named viaagencyBranding,2e3d4f2c); owners are forwarded topackages-agency-billingwhen the agency takes payment online. See Free Session, Paywall & Trials. - Payment issues.
agency.payment_issueflag andcompanyPaymentIssue/dismissCompanyPaymentIssueendpoints surface dunning state; cancel reasons persist on the subscription. - Low agency wallet warning (
AgencyWalletLowJob, every 6h,b4a697fc7): emails the agency owner (agency/wallet-low.html) whenwallet_creditsfalls below the agency's auto-rechargethreshold_creditsif set, else 2000 ($20). Once per dip (wallet_low_notified_atstamped on the way down, cleared on recovery). Skips agencies with auto-recharge enabled and configured (that path already mails on decline) and agencies that never used the wallet. Needed because an empty agency wallet stops number rentals, calls, SMS and Agent K across every client. - Opening transfer on Add Client debits this wallet — minimum per agency
opening_wallet_transfer_credits(super-admin; see Managing Companies). - AppSumo agencies have a $0
agency_subscriptionsrow withappsumo_package_id; seats come from the tier, and a downgrade below in-use seats locks the portal (423APPSUMO_SEAT_LIMIT) until clients are archived or seats bought — see AppSumo Licensing. - Calculations are tax-inclusive.
subscribe-calculationsreturns GST so the displayed total matches the eventual invoice.
Plan & limits
- Sub-account capacity = the agency package's
sub_accounts+ any sub-account add-ons (verify exact slot counts and prices per plan — none are hard-coded in this cluster). - Trial availability/duration depends on the package's
trialflag and the agency'strial_duration(verify).
Technical implementation
- Views:
frontend/src/views/agency/SubscriptionManagement.vue,frontend/src/components/agency/subscription/*,frontend/src/views/agency/subscriptions/{List,Detail}.vue - Routes:
frontend/src/router/agency.js(subscription-management children +agency-subscriptions,agency-subscription-detail) - Repository:
frontend/src/repositories/agency/index.js - Controller:
backend/app/controllers/AgencyController.js(subscribe,changePackage,unsubscribe,reactivateSubscription,buyAddon,subscribeCalculations,packageChangeCalculations) — see backend service - Models:
AgencySubscriptionModel(incl.new_package_idfor deferred downgrade),AgencyPackageModel,AgencyAddonModel,SubscriptionModel(per-client)
Related
- Agency Portal — Overview
- Packages — client packages vs. agency packages
- Managing Companies — per-client cancel/reactivate
- Dashboard