Skip to main content

Packages

Audience: Agency-success / Sales / Management · Where in app: /agency/packages (list, create, edit) · Plan availability: Agency tier; route gated by agency.manage_packages

Packages here are the client-facing plans an agency defines and assigns to its sub-accounts — "Basic", "Pro", etc. The agency sets the user count, AI-credit allotment, and renewal window; it does not set a Stripe price here (the agency bills its clients off-platform, or via whatever the agency arranges). This is distinct from agency packages (AgencyPackageModel), which are the SKUs the agency itself subscribes to and which grant sub-account slots — those live in Subscriptions.

Two different "package" concepts
  • Client packages (this page) — PackageModel rows scoped by agency_id. Created at POST /agencies/packages. Fields: title, description, default_users, ai_credits, expiry_days, user_emails. No Stripe price; visibility: private, base_price: 0.
  • Agency packages — AgencyPackageModel rows with amount, currency, sub_accounts, stripe_price_id. These are the platform's plans the agency buys to get sub-account capacity. See Subscriptions. Don't confuse the two — the code paths and models are different.

What it does​

  • Lets an agency create / edit the packages it offers clients.
  • Each package defines default user seats and a monthly AI-credit allotment granted to any client placed on it.
  • Optionally restricts a package to specific client emails (user_emails).
  • Packages appear in the company-create and package-assign dropdowns (see Managing Companies).

How it works​

The package list/create/edit screens are gated by the route meta agencyPermission: 'agency.manage_packages'. The Edit screen reuses the platform Billing repository (getPackage, createPackage, updatePackage) but the create/update endpoints are the agency ones, which stamp agency_id and force visibility: 'private', base_price: 0, currency: 'USD', status: 'active'. So a client package is a private, agency-scoped PackageModel row with no purchasable Stripe price — it's an allocation template, not a checkout SKU.

When the package is assigned to a client (during company create or via assign-package), the client's SubscriptionModel is created/updated with package_id and remaining_ai_credits = pkg.ai_credits. AI-credit and seat limits then flow from the package onto the sub-account.

Source: frontend/src/views/agency/packages/Edit.vue and AgencyController (createCompanyPackage, updateCompanyPackage).

Configuration & options​

Package fields (packages/Edit.vue)​

FieldDefaultRequiredNotes
Title (title)''yese.g. "Basic Plan"
Description''yesShown to client
Expiry Days (expiry_days)30no (defaults to 30)Days until the client subscription needs renewal
Default Users (default_users)5yesSeats included; min 1
AI Credits (ai_credits)1000yesMonthly AI credits granted to the client; min 0
User Restrictions (user_emails[])[]noIf set, package is only available to these emails; empty = available to anyone. Empty strings are filtered on submit

Validation is vee-validate + zod (title/description non-empty, default_users ≥ 1, ai_credits ≥ 0, expiry_days ≥ 1, valid emails).

Backend create/update​

ActionEndpointControllerFields persisted
CreatePOST /agencies/packagescreateCompanyPackageagency_id, title, description, default_users, ai_credits, user_emails, expiry_days (default 30), base_price: 0, currency: 'USD', status: 'active', visibility: 'private'
UpdatePUT /agencies/packages/:idupdateCompanyPackagetitle, description, default_users, ai_credits, user_emails, expiry_days
ListGET /agency-packages (getPackages)—Packages available to the agency

Note: the read repository in frontend/src/repositories/agency/index.js (getPackages) hits /agency-packages, while the Edit screen reads individual packages through the platform Billing repo (getPackage). Both surface PackageModel data; the agency-scoped writes are what make a package "a client package".

Archive / restore / delete (c0a749e47, frontend ccfa3603)​

AgencyClientPackageController (agency users only, own agency_id packages; injected in container.js):

EndpointDoes
GET /agencies/client-packages/:id/usagein_use, can_delete, active_clients, past_clients, up to 10 client_names, archived
POST /agencies/client-packages/:id/archivesets archived_at and signup_visible: false
POST /agencies/client-packages/:id/unarchiveclears archived_at; signup_visible stays off deliberately
DELETE /agencies/client-packages/:id409 PACKAGE_IN_USE (with usage) if in use, else hard delete

"In use" is one rule, lib/packageUsage.js packagesInUse: any subscription with it as package_id or new_package_id (any status — expired billing history counts), an AgencyClientBillingModel row, or a company's registered_package_id. GET /package returns in_use per package and hides archived ones unless ?archived=1 (all = both). Archived packages are excluded from Add Client (createCompany / GHL create), the private per-client package lookup, and every public sign-up query (AgencySignupController). UI (views/agency/packages/List.vue): filter tabs Latest (7 days) / All / Archived (persisted in localStorage kk_agency_packages_filter), In use / Archived badges, Archive + Delete icon buttons only when !in_use, Restore on archived cards, ConfirmDialog flows that fall back to "Archive instead" when the server reports usage.

Duplicate mode​

Edit supports ?duplicate=<id> — pre-fills the form from an existing package, titles it " (Copy)", and creates a new one on submit.

Behaviors & edge cases​

  • Price lives in client_billing, not base_price. Client packages keep base_price: 0 / currency: 'USD'; what the client pays the agency is the optional Stripe Connect price (client_billing, set via PUT /agencies/stripe-connect/packages/:id/price) plus signup_visible for the public signup page — see Client Billing. Unpriced packages are billed off-platform as before.
  • Private + agency-scoped. Created packages are visibility: 'private' and tagged agency_id, so they never appear in the public platform pricing and aren't visible to other agencies.
  • expiry_days defaults to 30 server-side even though the model default is 7 — the agency controller overrides it when omitted.
  • Email restriction is a filter, not an invite. user_emails limits which client emails can be placed on the package; it does not send anything.
  • AI credits are per-package. Changing a package's ai_credits affects newly-assigned/renewed clients; existing clients refresh on their renewal cycle (see Managing Companies).
  • Permission gate. Staff without agency.manage_packages can't reach these routes (route meta), and the backend write checks isAgencyUser.

Plan & limits​

  • The agency tier governs whether packages can be created at all (verify).
  • Seat (default_users) and credit (ai_credits) numbers are agency-chosen, not platform-fixed — there is no documented ceiling in this code (verify any platform cap).

Technical implementation​

  • Views: frontend/src/views/agency/packages/{List,Edit}.vue
  • Routes: frontend/src/router/agency.js (agency-packages, -create, -edit; meta agencyPermission: 'agency.manage_packages')
  • Repositories: frontend/src/repositories/agency/index.js (getPackages, createPackage, updatePackage), frontend/src/repositories/Billing (getPackage)
  • Controller: backend/app/controllers/AgencyController.js (createCompanyPackage, updateCompanyPackage) — see backend service
  • Models: PackageModel (client packages, agency_id-scoped), contrast AgencyPackageModel (agency's own plans)