> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/billing/subscriptions.md).

# Subscriptions

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/subscriptions.md).
{% endhint %}

A **site** has a **plan**: a **package** of limits and switches that Snapfix staff give it for a period. Customers pay for Snapfix with a **subscription** in Stripe, which they start from a [payment link](https://docs.snapfix.com/product/features/billing/payment-links.md); iOS also sells plans in the App Store, but no purchase reaches Snapfix ([In-app purchase](https://docs.snapfix.com/product/features/billing/in-app-purchase.md)). On the web, site admins open Stripe's billing portal from the "Your subscription" tab of the **Site Console**, to see invoices, change the payment method or cancel. The plan's limits are applied unevenly: the **free limit** stops task status changes on free and churned sites with more than 100 tasks on the web and Android, and the apps stop new tasks and new users at the plan's limits, which the web and the server do not check.

## Rules

### Managing the subscription (web)

* Only role "Admin" sees the "Your subscription" tab, and only on a site whose `hasSubscribed` is true ([Your subscription](https://docs.snapfix.com/how-the-apps-work/screens/billing/subscription.md)). The QA site has no subscription, so the tab was not seen live \[[ASK-135](https://github.com/snapfix/docs/blob/main/ASK.md#ask-135-which-qa-site-can-show-the-your-subscription-tab)].
* `hasSubscribed` is true when the site's newest `stripe_subscription` row records a successful payment or an update, and Stripe still returns that subscription ([`GET /v1/app/parents/{uuid}`](https://docs.snapfix.com/engineering-reference/api/console.md#get-v1appparentsuuid); api\_php\_live\_v2 @ ef3c4319f6, `app/Services/StripeService.php:97-112`, `app/Models/ParentModel.php:192-198`).
* Only the sandbox Stripe webhook writes `stripe_subscription` rows. The live webhook only stores each event, and no route records a live subscription, so on production sites the tab shows only if something outside the repos writes the row \[[ASK-142](https://github.com/snapfix/docs/blob/main/ASK.md#ask-142-who-records-live-stripe-subscriptions)] ([`POST /wh-production`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-wh-production)).
* Opening the tab asks for a Stripe billing portal session; the web keeps the link for each site until the page reloads ([`GET /v1/app/parents/{uuid}/create-session`](https://docs.snapfix.com/engineering-reference/api/billing.md#get-v1appparentsuuidcreate-session)). The portal shows the invoice history and lets the admin change the payment method and cancel the subscription.
* The server gives the session only to a site admin; a blocked admin still gets one. A group admin can open the tab's address, but the session is refused and the page goes to Site Details.
* Members who are not admins can still read billing details the web hides from them: the site read returns the Stripe customer ID and subscription, and the apps' site detail action the VAT details and subscription. Whether they should is open \[[ASK-124](https://github.com/snapfix/docs/blob/main/ASK.md#ask-124-should-members-who-are-not-admins-see-the-sites-billing-details)].

### How a site gets its plan

* Staff give a site a package on the admin app's [Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md), from now for one year. The route behind it, [`PUT /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#put-v4parent-pack), checks no staff role.
* The sandbox webhook records a new test subscription, but its package link insert always fails, so a test payment sets no package ([`POST /wh-sandbox`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-wh-sandbox)).
* A live payment, and a cancellation in the portal, change neither the site's package nor its subscription rows, because the live webhook only stores the event \[[ASK-142](https://github.com/snapfix/docs/blob/main/ASK.md#ask-142-who-records-live-stripe-subscriptions)].
* An App Store purchase reaches no Snapfix server, so it changes no plan \[[ASK-143](https://github.com/snapfix/docs/blob/main/ASK.md#ask-143-how-does-an-app-store-purchase-reach-a-sites-plan)].
* Android reads each site's package when the group list loads, and iOS when it loads its groups (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/GroupListingFragment.java:310`; ios @ aa31967ac8, `SnapFix/BusinessListingVC.swift:587-600`; [`parent_packages`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionparent_packages), [`package_permissions`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionpackage_permissions)).
* Until Android has a site's package, it applies a permission with no limits (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/model/PaywallPermission.java:204-217`, `app/src/main/java/gmail/com/snapfixapp/utils/PrefUtils.java:200-209`).
* The web reads no plan. Its plan reader has no caller, and the side menu call that would load each site's package is commented out (web\_app\_v2 @ 0989b8e685, `src/app/services/paywall/paywall-helper/paywall-helper.service.ts:33-41`, `src/app/components/side-menu/account-list-menu/account-list-menu.component.ts:298-301`).

### Free limit on task statuses

* A site with customer type `0` (uncategorised, the default for a new site) or `churn` may change task statuses only while it has 100 tasks or fewer. The count includes deleted tasks and tasks in deleted groups ([`GET /v1/app/parents/{uuid}/can-change-status`](https://docs.snapfix.com/engineering-reference/api/console.md#get-v1appparentsuuidcan-change-status); api\_php\_live\_v2 @ ef3c4319f6, `app/Http/Controllers/v1/Versions/v1_0/App/ParentController.php:60`, `:225-238`, `app/Services/ParentService.php:311-318`).
* The limit depends on the customer type only, not on the subscription or the package. The types `paying_customer`, `sales_trial`, `test` and `investor_probono` have no limit (`app/Enums/CustomerType.php:7-12`). The 100 is fixed in the code, not the package's task limit \[[ASK-148](https://github.com/snapfix/docs/blob/main/ASK.md#ask-148-which-rule-should-the-free-limit-on-status-changes-follow)].
* The route answers for any site, without a membership check.
* The limit applies after the group's colour permission check, to everyone who may change the status, group admins included (web\_app\_v2 @ 0989b8e685, `src/app/services/task/task-helper/task-helper.service.ts:496-552`; android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/fragment/JobChatFragment.java:5796-5803`).
* Over the limit, the change is refused and a dialog says "You have reached the free limit of Tasks you can Snapfix (from Red to Yellow to Green)." and "You can still continue to create new Tasks." Its button "See subscriptions options" opens the pricing page on the web and the sales page on Android ([Subscription limit](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#subscription-limit); [Choose plan: platform differences](https://docs.snapfix.com/how-the-apps-work/screens/billing/choose-plan.md#platform-differences)).
* The web asks the server before a single status change, from the task's traffic light and from the workflow board (`src/app/pages/task/task-traffic-light/task-traffic-light.component.ts:116`, `src/app/pages/task-list/task-list-workflow-view/task-list-workflow-view.component.ts:359-368`). If the question fails, the change goes ahead (`task-helper.service.ts:649-660`). Each question counts all of the site's tasks.
* The web does not check the bulk status dialog, the checklist's automatic amber and green moves, or asset registers (`src/app/pages/task/task-traffic-light/task-traffic-light.component.ts:109-117`; `task-helper.service.ts:545-552`).
* Android counts the tasks on the device, from the Firebase counter `task_count`, which drops when a task is deleted and drifts (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/TaskListingActivity.java:889-896`, `app/src/main/java/gmail/com/snapfixapp/utils/InAppValidatorUtils.kt:16-31`). It checks single and selected tasks, asset status changes and the checklist's automatic moves (`TaskListingActivity.java:7725-7729`, `JobChatFragment.java:5940-5943`, `app/src/main/java/gmail/com/snapfixapp/activity/ViewCheckListActivity.kt:2705-2718`).
* Because the two count differently, the same site can be refused on the web and allowed on Android \[[ASK-148](https://github.com/snapfix/docs/blob/main/ASK.md#ask-148-which-rule-should-the-free-limit-on-status-changes-follow)].
* iOS never refuses a status change: its check returns `false` before it runs \[[ASK-20](https://github.com/snapfix/docs/blob/main/ASK.md#ask-20-should-ios-enforce-the-free-plan-limit-on-status-changes)] (ios @ aa31967ac8, `AppUtility.swift:3876-3877`). The server's status routes refuse nothing either \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].

### Other plan limits and switches

* A package sets a task limit; `-1` means no limit (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/utils/PaywallUtils.java:141-148`). When no new tasks are left, the apps stop new tasks with "No new tasks left in this account." ([Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md#the-plans-task-limit)). Some paths skip the check, and the web and the server never check it \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* The apps stop adding users at the package's user limit; the web and the server do not check it \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/AddUserFromContactListActivity.kt:640-645`; ios @ aa31967ac8, `SnapFix/AddUserToGroupVC/AddFromContactVC.swift:205-214`). The group limit is stored, and no code reads it (`PaywallPermission.java:257-258`).
* Time and cost, asset registers, NFC and the report types are switched off by the package in some app checks; the web and the server check none of them \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* Android opens the planner with no plan check: its old check is commented out (android @ 86068bfeea, `app/src/main/java/gmail/com/snapfixapp/activity/BusinessListingActivity.java:958-966`). The iOS planner lock never runs \[[ASK-146](https://github.com/snapfix/docs/blob/main/ASK.md#ask-146-is-the-ios-planner-tab-lock-still-meant-to-exist)], and nothing checks the task limit when a planner is saved or its tasks are created \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* A package also has an `apps` block with an on/off switch and free-trial days for iOS, Android and the web. No app or server uses them \[[ASK-149](https://github.com/snapfix/docs/blob/main/ASK.md#ask-149-what-do-a-plans-app-switches-and-free-trial-days-do)].
* The apps read the site's task and user counts from a usage node in Firebase. The php-apis Basic login can rewrite any site's node \[[ASK-12](https://github.com/snapfix/docs/blob/main/ASK.md#ask-12-which-settings-do-the-production-api-servers-use)].

## Flow

The free limit, on the web and Android (iOS skips it \[[ASK-20](https://github.com/snapfix/docs/blob/main/ASK.md#ask-20-should-ios-enforce-the-free-plan-limit-on-status-changes)]):

```mermaid
flowchart TD
  change["Change a task's status"] --> perm{"Group permission for the colour?"}
  perm -- "no" --> denied["Refused: permission message"]
  perm -- "yes" --> type{"Customer type 0 or churn?"}
  type -- "no" --> saved["Status changes"]
  type -- "yes" --> count{"More than 100 tasks, deleted ones included?"}
  count -- "no" --> saved
  count -- "yes" --> limit["Refused: limit dialog"]
  limit --> link["Web: pricing page. Android: sales page"]
```

The billing portal, on the web:

```mermaid
flowchart LR
  tab["Admin opens Your subscription"] --> recorded{"hasSubscribed?"}
  recorded -- "no" --> details["Site Details"]
  recorded -- "yes" --> admin{"Site admin?"}
  admin -- "no" --> details
  admin -- "yes" --> session["Billing portal session"]
  session --> stripe["Stripe: invoices, payment method, cancel"]
```

## Platforms

| Capability                                             | Web                                                                                                                              | iOS                                                                                                                              | Android                                |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Buy a plan                                             | Through a [payment link](https://docs.snapfix.com/product/features/billing/payment-links.md)                                     | App Store, not recorded in Snapfix ([In-app purchase](https://docs.snapfix.com/product/features/billing/in-app-purchase.md))     | No; a sales sheet and the limit dialog |
| Open the billing portal                                | Site admins, on a site with a recorded subscription                                                                              | No                                                                                                                               | No                                     |
| Free limit on a single status change                   | Yes                                                                                                                              | No \[[ASK-20](https://github.com/snapfix/docs/blob/main/ASK.md#ask-20-should-ios-enforce-the-free-plan-limit-on-status-changes)] | Yes                                    |
| Free limit on bulk, automatic and asset status changes | No                                                                                                                               | No \[[ASK-20](https://github.com/snapfix/docs/blob/main/ASK.md#ask-20-should-ios-enforce-the-free-plan-limit-on-status-changes)] | Yes                                    |
| Limit dialog button                                    | Pricing page                                                                                                                     | None                                                                                                                             | Sales page                             |
| Task limit on new tasks                                | No \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] | Yes, with gaps                                                                                                                   | Yes, with gaps                         |
| User limit                                             | No \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] | Yes                                                                                                                              | Yes                                    |
| Plan switches (time and cost, assets, NFC, reports)    | No \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)] | Some                                                                                                                             | Some                                   |

## Screens

* [Your subscription](https://docs.snapfix.com/how-the-apps-work/screens/billing/subscription.md): the web tab and its billing portal link.
* [Snapfix payment](https://docs.snapfix.com/how-the-apps-work/screens/billing/payment-page.md): the payment page that starts a subscription.
* [Choose plan](https://docs.snapfix.com/how-the-apps-work/screens/billing/choose-plan.md): the iOS plan purchase, and Android's upgrade sheet.
* [Task detail: subscription limit](https://docs.snapfix.com/how-the-apps-work/screens/tasks/task-detail.md#subscription-limit): the dialog when the free limit stops a status change.
* [Pick group: task limit banner](https://docs.snapfix.com/how-the-apps-work/screens/tasks/pick-group.md#task-limit-banner): the stop on new tasks.
* [Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md): staff build packages and give sites their package.

## API and data

* [`GET /v1/app/parents/{uuid}/create-session`](https://docs.snapfix.com/engineering-reference/api/billing.md#get-v1appparentsuuidcreate-session): the billing portal session (web).
* [`GET /v1/app/parents/{uuid}`](https://docs.snapfix.com/engineering-reference/api/console.md#get-v1appparentsuuid): `hasSubscribed`, the subscription and the customer type (web).
* [`GET /v1/app/parents/{uuid}/can-change-status`](https://docs.snapfix.com/engineering-reference/api/console.md#get-v1appparentsuuidcan-change-status): the free limit (web).
* [`POST ?action=parent_packages`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionparent_packages) and [`POST ?action=package_permissions`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-actionpackage_permissions): each site's package and its limits (iOS, Android).
* [`PUT /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#put-v4parent-pack): staff give a site a package (admin app).
* [`POST /wh-production`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-wh-production) and [`POST /wh-sandbox`](https://docs.snapfix.com/engineering-reference/api/billing.md#post-wh-sandbox): the Stripe webhooks.
* Tables: [`tPri_Parent`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_parent.md) (the customer type, `fCustomerType`, default `0`), [`stripe_subscription`](https://docs.snapfix.com/engineering-reference/db/tables/stripe_subscription.md) (recorded subscriptions), [`stripe_log`](https://docs.snapfix.com/engineering-reference/db/tables/stripe_log.md) (Stripe events), [`package_server`](https://docs.snapfix.com/engineering-reference/db/tables/package_server.md) and [`package_server_pricing`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_pricing.md) (packages and their Stripe prices), [`package_server_parent`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_parent.md) (each site's package for a period) and [`package_client_parent`](https://docs.snapfix.com/engineering-reference/db/tables/package_client_parent.md) (the copy the apps read).

## Depends on

* [Payment links](https://docs.snapfix.com/product/features/billing/payment-links.md) and [In-app purchase](https://docs.snapfix.com/product/features/billing/in-app-purchase.md): the two ways to buy a plan.
* [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md): staff build packages and prices.
* [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md) and [Checklists](https://docs.snapfix.com/product/features/checklists/checklists.md): the status changes, manual and automatic, that the free limit stops.
* [Creating tasks](https://docs.snapfix.com/product/features/tasks/task-creation.md): the task limit for new tasks.
* [Planned tasks](https://docs.snapfix.com/product/features/planner/planned-tasks.md): no plan check on the planner.
* [Site users](https://docs.snapfix.com/product/features/console/site-users.md): the admin role, and the user limit.
* [Site details](https://docs.snapfix.com/product/features/console/site-details.md): the Site Console, and the site record that carries the customer type.
* [Time and cost](https://docs.snapfix.com/product/features/tasks/time-and-cost.md), [Asset registers](https://docs.snapfix.com/product/features/assets/asset-registers.md) and [Task reports](https://docs.snapfix.com/product/features/reports/task-reports.md): features a package can switch off on some platforms \[[ASK-23](https://github.com/snapfix/docs/blob/main/ASK.md#ask-23-should-plan-limits-be-enforced-on-the-web-and-the-server)].
* Stripe (subscriptions and the billing portal) and the App Store, both outside Snapfix.

## Edge cases

* **No recorded subscription:** no tab, and its address opens Site Details \[[ASK-135](https://github.com/snapfix/docs/blob/main/ASK.md#ask-135-which-qa-site-can-show-the-your-subscription-tab)].
* **Billing session fails:** the API's message, such as "Access denied", "Account does not have a customer id" or "Failed to create session", opens in an alert, and the page goes to Site Details at once, which removes the alert ([Your subscription: states](https://docs.snapfix.com/how-the-apps-work/screens/billing/subscription.md#states)).
* **Deleted tasks:** they still count on the web, so deleting tasks frees no room there.
* **Offline (Android):** the limit uses the task count last stored on the device.
* **Several sites:** each site has its own customer type, package and task count.
* **Old portal actions:** two php-apis actions that nothing calls open any Stripe customer's billing portal for a signed-in member of any site ([Billing API](https://docs.snapfix.com/engineering-reference/api/billing.md)).
* **App Store wording:** the web's limit dialog points to "subscription options on the App Store and Website", but an App Store purchase changes no plan \[[ASK-143](https://github.com/snapfix/docs/blob/main/ASK.md#ask-143-how-does-an-app-store-purchase-reach-a-sites-plan)].
* **Time zones:** none.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/billing/subscriptions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
