> 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/how-the-apps-work/screens/staff/paywall.md).

# Paywall

{% 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)). Platforms: web. [Source on GitHub](https://github.com/snapfix/docs/blob/main/spec/screens/staff/paywall.md).
{% endhint %}

Staff build the paywall packages of each marketing bundle, with their prices and permissions, copy each price's payment link, and set which package a site has.

* **Where:** admin app `/paywall`; menu "Paywall", shown only to the staff below.
* **Who:** usernames on the app's built-in `adminUsers` list whose sign-in token is their own (webadmin\_angular @ db972390b8, `src/app/shared/config.ts:21-28`, `src/app/services/payment/payment.service.ts:180-193`). The menu hides the item from everyone else, and the route sends them to Home; both checks run in the browser. The package actions check no staff flag, and neither do the site package routes.
* **Feature:** [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md)

## Layout

1. The title "Paywall". Above the tabs, the bar of the open tab:
   * **Packages:** a round "+" button with "Add new paywall package", and "Select a bundle", a searchable select on the first bundle at first, disabled while the bundles load.
   * **Parents:** "Search parent", a field with the placeholder "Parent name".
2. The tabs "Packages" and "Parents", both enabled.

**Packages tab.** The selected bundle's packages, 10 per page by default (10, 20, 50 or 100) with a page jump. Columns: an expand arrow (only for a package with prices), "Name", "Description" and "Type", which all sort in the browser, and "Action" with an "Edit" button. An expanded package lists its prices:

* "Description", sorted at first; a price without one shows "---".
* "Amount", the stored amount divided by 100, shown as money in its currency.
* "Interval".
* "Url": a "Copy" button.

**Parents tab.** Every site, 10 per page by default (10, 50, 100, 200 or 500) with a page jump, paged and sorted on the server. Columns: "Name", "Address" and "Created Date" (as "MMM dd, yyyy"), which sort; "Groups", which counts member rows rather than groups; "Jobs"; "Users"; "Package"; and "Action" with an "Update package" button. On a page with two or more sites, every site shows 0 jobs and the built-in "Unlimited Package" ([`GET /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#get-v4parent-pack)).

## Inputs

| Field           | Type              | Required                   | Default          | Rules and messages                                                                                                                                   |
| --------------- | ----------------- | -------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Select a bundle | Searchable select | Yes, once the bundles load | The first bundle | Choosing a bundle empties the table and loads its packages. A read-only bundle disables "+" and every "Edit", with the tooltip "Bundle is readonly". |
| Parent name     | Text              | No                         | Empty            | Sent to the server as the search 500 ms after typing stops; it goes back to page 1. Matches part of the site name, ignoring case.                    |

## Actions

| Action                                             | Who          | What happens                                                                                                                                                                      | API                                                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Open the page                                      | Listed staff | Loads the bundles, then the first bundle's packages and the currencies.                                                                                                           | [`POST ?action=snapfix_bundles`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionsnapfix_bundles), [`POST ?action=snapfix_packages`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionsnapfix_packages), `?action=currencies_list` in the [Reference API](https://docs.snapfix.com/engineering-reference/api/reference.md) |
| Choose a bundle                                    | Listed staff | Loads that bundle's packages.                                                                                                                                                     | [`POST ?action=snapfix_packages`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionsnapfix_packages)                                                                                                                                                                                                                                              |
| "+" ("Add new paywall package")                    | Listed staff | Opens [Create Paywall Package](#create-paywall-package). Disabled while the packages or currencies load, with no bundle, and for a read-only bundle.                              | None                                                                                                                                                                                                                                                                                                                                                                    |
| "Edit" (a package)                                 | Listed staff | Opens [Edit package](#edit-package).                                                                                                                                              | None                                                                                                                                                                                                                                                                                                                                                                    |
| "Copy" (a price)                                   | Listed staff | Copies the payment app's single-price link for the price and shows "Price url copied to clipboard.". That link's page cannot take a payment: it always ends in "invalid package". | None                                                                                                                                                                                                                                                                                                                                                                    |
| List, search, sort or page the sites (Parents tab) | Listed staff | Loads that page of sites with their counts and package.                                                                                                                           | [`GET /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#get-v4parent-pack)                                                                                                                                                                                                                                                                |
| "Update package" (a site)                          | Listed staff | Opens [Update parent package](#update-parent-package).                                                                                                                            | None                                                                                                                                                                                                                                                                                                                                                                    |

## States

* **Loading:** the bundle select and both tables show their loading state; "+" stays disabled until the packages and currencies have loaded.
* **Empty:** a bundle with no packages, or a search with no site, shows an empty table.
* **Error:** a bundle list that is not a success shows its message, or "Internal server error"; a failed bundle request shows nothing. A package list that is not a success shows the server's message and leaves the table empty. A failed site list empties the table with no message. When the currency list fails or has no supported currency, the create dialog offers "USD", "GBP" and "EUR".
* **No permission:** staff off the list never see the page (see Who).

## Dialogs and sheets

### Create Paywall Package

"Create Paywall Package", for the selected bundle: an accordion of three panels, "Package" (open at first), "Prices" and "Permissions". Each panel header shows a check or an error mark.

| Field                   | Type                                   | Required   | Default                                           | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------- | -------------------------------------- | ---------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name                    | Text                                   | Yes        | Empty                                             | No message; the "Package" panel shows its error mark while it is empty.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| Type                    | Select: "Core" or "Supplement"         | Yes        | "Core"                                            |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| Description             | Text                                   | No         | Empty                                             | Sent as an empty text when blank.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Price currency          | Select of the supported currency codes | Yes        | The first currency not yet used with an interval  | Sent in lower case. A currency already used with the row's interval is disabled.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| Price amount ("Amount") | Number                                 | Yes        | Empty                                             | 0 or more, so a free price passes \[[ASK-218](https://github.com/snapfix/docs/blob/main/ASK.md#ask-218-should-a-zero-amount-be-accepted-for-card-payments-and-paywall-prices)]. Sent multiplied by 100, without rounding.                                                                                                                                                                                                                                                                                |
| Price interval          | Select: "Month" or "Year"              | Yes        | The first interval not yet used with the currency | An interval already used with the row's currency is disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| Permissions             | JSON editor in form mode               | Yes, valid | The app's built-in permissions                    | Checked against the app's built-in schema. Only values change: key names cannot be edited, and `paywall_version` cannot be edited at all. A limit below its warning shows a line under the dialog: "task limit should be greater than limit\_warning", "task limit\_year should be greater than limit\_year\_warning" (the same for "group" and "user") or "ios free\_trial\_days should be greater than free\_trial\_days\_warning" (the same for "android" and "web"), using the internal field names. |

* One price row to start; its "Remove" button (tooltip "Remove") is disabled, so at least one price stays. "Add price" (tooltip "Add") is disabled once every currency has a price for both intervals.

| Action   | Who          | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                        | API                                                                                                                                    |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| "Save"   | Listed staff | Disabled until the package fields, the prices and the permissions are valid. Sends the bundle, the name, type, description, prices and permissions, with the signed-in user as creator. When the edited permissions have the default keys they are sent; when a key differs, the built-in defaults are sent instead. On success "Success" shows, the dialog closes and the package is listed first. A refusal shows the server's message and the dialog stays open. | [`POST ?action=create_snapfix_package`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actioncreate_snapfix_package) |
| "Cancel" | Listed staff | Closes. Disabled while saving, as are the close button and a click outside.                                                                                                                                                                                                                                                                                                                                                                                         | None                                                                                                                                   |

### Edit package

Titled with the package name, and " (In use)" when a site uses the package; the title is built as HTML from the name. The body is the permissions editor of the create dialog, with the package's permissions, read-only when the package is in use. Its limit check runs at once, so a stored package that breaks a limit opens with the message and "Save" disabled.

| Action   | Who          | What happens                                                                                                                                                                                                                                   | API                                                                                                                                  |
| -------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| "Save"   | Listed staff | Hidden when the package is in use; disabled while there is an error. Sends only the permissions, chosen as in the create dialog; the name, type, description and prices do not change here. On success "Success" shows and the row is updated. | [`POST ?action=update_package_schema`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionupdate_package_schema) |
| "Cancel" | Listed staff | Closes. Disabled while saving.                                                                                                                                                                                                                 | None                                                                                                                                 |

### Update parent package

"Update parent package".

| Field            | Type                                        | Required | Default                                                   | Rules and messages                                                                                                                                                                       |
| ---------------- | ------------------------------------------- | -------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parent           | Text                                        |          | The site's name                                           | Read-only.                                                                                                                                                                               |
| Select a bundle  | Searchable select of every bundle           | No       | The bundle whose name matches the site's marketing bundle | Choosing a bundle loads its packages, and it also switches the Packages tab to that bundle. A site with no matching bundle leaves the Packages tab without a bundle until one is chosen. |
| Select a package | Searchable select of that bundle's packages | Yes      | The site's current package, matched by ID, then by name   | Disabled while the packages load.                                                                                                                                                        |

| Action   | Who          | What happens                                                                                                                                                                                                                                                                                 | API                                                                                                      |
| -------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| "Save"   | Listed staff | Disabled until a package is chosen. Sends the site, the package and the signed-in user, and no dates, so the server gives the package from now for one year and marks the site's other package rows deleted. On success "Success" shows, and the row shows the new package and bundle names. | [`PUT /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#put-v4parent-pack) |
| "Cancel" | Listed staff | Closes. Disabled while saving.                                                                                                                                                                                                                                                               | 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/how-the-apps-work/screens/staff/paywall.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.
