Feature access: how DriveFlow decides what a school can use¶
Applies to: Owner and Administrator (to understand what is switched on); developers. Last reviewed: 2026-11-18.
This page explains, step by step, how DriveFlow decides whether a school may use a feature, what a user sees when the answer is no, and how the API enforces it.
The three layers¶
A user can do something only when all three say yes:
- Subscription: the school's trial or paid period is still running.
- Feature: the school's plan includes the feature, and, for add-on features on a paid plan, the add-on is paid up.
- Permission: the user's role has the permission for the action (for example Leads.View).
This page is about layers 1 and 2. Permissions and roles are a separate subject (see Roles and permissions).
DriveFlow SuperAdmin users are not bound to any school's plan; for them every check passes.
How the decision is made¶
For each school, the server builds an "access" record:
flowchart TD
A["Find the school's latest subscription (ignoring checkouts that were never paid)"] --> B{None found?}
B -->|Yes| X[No access]
B -->|No| C["Work out the effective status: Trial or Active, and the end date has passed -> Expired"]
C --> D[Access = status is Trial or Active]
D --> E["Features = every enabled feature of the plan, with its limit (blank = unlimited)"]
E --> F{"Status is Active (a paid plan)?"}
F -->|Yes| G["For each active add-on whose feature is in the plan: monthly add-on -> paid-until date still in the future? SMS (prepaid) -> credits above zero?"]
G -->|If not| H["Remove that feature and note it as 'add-on due'"]
F -->|No| I{Status is Trial?}
I -->|Yes| J["Add-on features in the plan are left on (free on trial)"]
Consequences worth knowing:
- A feature not in the plan can never be unlocked by an add-on. The add-on step only removes features; it never adds one.
- On the trial, add-ons are not checked. Leads and Online Booking work because the trial plan includes them.
- An expired subscription has no features, whatever the plan and whatever add-ons were paid.
- A feature is identified by a code, for example
LEADS. The codes and what each plan has are listed in Subscription plans.
Feature codes that are enforced¶
| Code | Protects |
|---|---|
STUDENTS |
Students (and the student limit) |
BOOKINGS |
Lessons, instructors' own lessons |
CALENDAR |
Calendar |
VEHICLES |
Vehicles (and the vehicle limit) |
INSTRUCTORS |
Instructors (and the instructor limit) |
MULTI_BRANCH |
The branch limit |
PAYMENTS |
Invoices, payments, students paying online |
REPORTS |
Reports |
QUOTES |
Quotes |
LEADS |
Leads, follow-ups, connecting a Facebook Page |
STUDENT_PORTAL |
The student portal and inviting students to it |
ONLINEBOOKING |
Lesson requests from the portal and their approval |
FLEET |
Fleet Management |
INSTRUCTOR_EARNINGS |
Instructor Earnings |
SMS, WHATSAPP |
Those notification channels |
MOBILE_APP |
The mobile app and push notifications |
EMAIL_NOTIFICATIONS is on every plan and is listed on plan cards; email is always available. API, WHITE_LABEL and ACCOUNTING exist as codes but nothing checks them.
Caching and how fast changes take effect¶
| Where | How long the answer is kept | When it is refreshed early |
|---|---|---|
| API server | 1 minute per school (in memory) | Cleared immediately when: a payment is confirmed, a subscription is cancelled or a cancellation undone, SMS credits reach zero or a failed SMS is refunded. |
| Web application | 5 minutes per signed-in session | Reloaded when you open the Subscription page, when the payment result page confirms a payment, and when Check again is clicked. |
| Mobile app | For the session | Re-checked at sign-in, when a saved session is restored, after a password change, and whenever the API refuses a request. |
In practice:
- After you pay, the feature is available at once in your own browser. Colleagues who are already signed in see the menu change within about five minutes, or immediately after refreshing the page.
- When a monthly add-on reaches its paid-until date, or a plan reaches its end date, nothing clears the cache at that instant; the API notices within a minute and each browser within five.
- Because the server cache is held in the memory of one server process, a deployment with several API servers could show a change up to a minute later on some of them.
Tip
If a colleague does not see a feature you have just paid for, ask them to refresh the page.
What the user sees when a feature is not available¶
Menu¶
Menu items are hidden when the plan (after the add-on check) does not include the feature: the Leads group, Instructor Earnings, Fleet, lesson requests, the invoicing and payments group, Quotes and Reports. A hidden item gives no explanation by itself.
Pages¶
Pages that can be reached by address explain themselves. For Leads:
| Situation | Panel shown |
|---|---|
| Plan includes Leads but the add-on is not paid | "Activate the Leads add-on" - "Leads is a paid add-on: a once-off setup fee, then a monthly fee. Any leads you already have are kept and come back as soon as it's paid." with Go to Billing, or "Ask your administrator to activate it." |
| Plan does not include Leads | "Leads are part of the Professional plan" with View plans |
The follow-ups page, the Integrations page and the Notifications settings page show equivalent messages for their features. Other pages may differ in how much they explain; the API refusal below is what ultimately applies.
Limits¶
Adding a record over the plan limit fails with, for example:
Your Professional plan allows up to 15 vehicles. Upgrade your plan to add more.
Limits apply to students, instructors, vehicles and branches; see Subscription plans.
How the API enforces it¶
A global filter (SubscriptionAccessFilter) runs before every controller action.
flowchart TD
A[Request arrives] --> B{"Not signed in, or the endpoint is anonymous?"}
B -->|Yes| OK1[Let through]
B -->|No| C["Load the school's access (from cache)"]
C --> D{"SuperAdmin or no school, on a web session?"}
D -->|Yes| OK2[Let through]
D -->|No| E{"Subscription not running, and endpoint is not marked 'allowed without subscription'?"}
E -->|Yes| R1[402 SUBSCRIPTION_EXPIRED]
E -->|No| F{"Mobile session, endpoint not marked 'allowed for a restricted mobile session', and plan lacks MOBILE_APP?"}
F -->|Yes| R2[403 MOBILE_APP_NOT_INCLUDED]
F -->|No| G{Endpoint requires a feature the access record lacks?}
G -->|Yes| R3[403 FEATURE_NOT_AVAILABLE]
G -->|No| OK3["Let through (permissions are checked separately)"]
Responses¶
Subscription ended - HTTP 402:
{ "message": "Your subscription has ended. Renew it under Settings > Subscription to continue using DriveFlow.", "code": "SUBSCRIPTION_EXPIRED" }
Feature not in the plan - HTTP 403:
{ "message": "Quotes is not included in your Starter plan. Upgrade your plan under Settings > Subscription to use it.", "code": "FEATURE_NOT_AVAILABLE", "feature": "QUOTES" }
Add-on not paid - HTTP 403:
{ "message": "Leads is a paid add-on. Activate or renew it under Settings > Billing to use it.", "code": "FEATURE_NOT_AVAILABLE", "feature": "LEADS" }
Mobile app not in the plan - HTTP 403 with code MOBILE_APP_NOT_INCLUDED; see Mobile app entitlements.
If the subscription lookup itself fails (for example the database is unreachable), the request fails. It is never let through.
Checks made inside the code¶
Besides the filter, some actions check a feature or limit themselves and fail with a plain error message (HTTP 400 style business error):
| Check | Where |
|---|---|
| Student, instructor, vehicle and branch limits | When creating one of them |
PAYMENTS |
When an action on a student or a booking would also create an invoice |
SMS, WHATSAPP |
When sending a test or manual notification on that channel; and silently, when the notification engine drops a channel the school does not have |
STUDENT_PORTAL |
When giving a student portal access |
ONLINEBOOKING |
When a student requests a lesson from the portal |
PAYMENTS plus the school's PayFast details |
When a student pays an invoice online |
INSTRUCTOR_EARNINGS |
When earnings are calculated for a completed lesson |
MOBILE_APP |
When deciding whether to send push notifications |
QUOTES, LEADS, ONLINEBOOKING, FLEET |
When building the header's search results and alerts |
The messages are:
- "Your subscription has ended. Renew it under Settings > Subscription to continue."
- "Feature is a paid add-on. Activate or renew it under Settings > Billing to use it."
- "Feature is not included in your Plan plan. Upgrade your plan to use it."
After expiry¶
No grace period
When the subscription has ended, the school has no features and no access: there is no grace period and no read-only mode. See Expiry, suspension and reactivation for the pages and endpoints that stay open.
Example¶
A Professional school has paid the Leads add-on until 20 June 12:00 and has 3 SMS credits.
- 20 June 11:59: the receptionist adds a lead. Fine.
- 20 June 12:02: she refreshes the page. The server's cached answer has expired, the add-on is past its date, so
LEADSis removed and recorded as "add-on due". The Leads menu group disappears and/leadsshows "Activate the Leads add-on". - The same afternoon three lesson reminders go out by SMS. After the third, the balance is zero, the server clears the cache, and
SMSis removed too. The next reminder goes by email only. - The Owner pays for Leads on the Billing page. The confirmation clears the cache; Leads is back for her at once and for the receptionist after a refresh.
Notes for developers¶
Developer details
- Plan features come from
SubscriptionPlanFeatures(plan, feature, enabled, limit). A missing row means "not included"; a null limit means "unlimited". - Mark an endpoint with
[RequiresFeature(FeatureCodes.X)]to gate it.[AllowWithoutSubscription]keeps an endpoint reachable after expiry.[AllowRestrictedMobileSession]additionally keeps it reachable for a mobile session whose plan has no mobile app; it is deliberately narrower. - Call
ISubscriptionAccessService.EnsureCanAddAsync(code)before creating a counted record, andInvalidate(companyId)after anything that changes a school's subscription or add-ons. - The web application's
SubscriptionStatetreats "unknown" (not loaded, or the API unreachable) as "allowed" so that a network hiccup does not lock the screen; the API remains the real gate.
Limitations and notes¶
- Hidden menu items do not tell the user why they are hidden. Users have to know to look at Settings > Subscription or Settings > Billing.
- The Leads menu group is hidden while the Leads add-on is unpaid, so the helpful "Activate the Leads add-on" panel is only reached by typing
/leadsor following an old link. - A paid add-on on a plan that does not include its feature has no effect and no warning is shown at the time of a downgrade.
API,WHITE_LABELandACCOUNTINGare not enforced anywhere because no functionality exists behind them.
Related articles¶
- Subscription plans: the feature matrix and limits.
- Add-ons: paid add-ons that switch features on.
- Expiry, suspension and reactivation: what stays open after expiry.
- Mobile app entitlements: mobile app access by plan.
- Roles and permissions: the permission layer.