> 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/staff/staff-billing.md).

# Billing setup

{% 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/staff-billing.md).
{% endhint %}

Snapfix staff set up how customers pay, in the [staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md). A few listed staff create **packages**, the sets of prices that a payment link charges: a card payment for one site, or a **Stripe package** with its services and prices. They build the **paywall packages** of each marketing **bundle**, whose permissions the apps read as plan limits, and set which package a site has. Any staff user also works through the **HubSpot deals** from Sales: they pick the deal's company and contact, link the Snapfix site, create a card subscription or a checkout link, take bank payments against a **mandate**, and create the setup link for a new customer. The customer then pays on the payment page ([Payment links](https://docs.snapfix.com/product/features/billing/payment-links.md)) or fills in the [setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md).

## Rules

### Who can use the tools

* "Credit Card Payment", "Stripe Payment" and "Paywall" open only for usernames on a list built into the app; anyone else goes to Home and the menu hides them. The check runs in the browser only ([Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md#pages-and-menu)).
* "Hubspot Deals" has no such list: every staff login opens it and can take payments \[[ASK-205](https://github.com/snapfix/docs/blob/main/ASK.md#ask-205-who-may-take-payments-on-hubspot-deals-and-create-sales-packages-and-payment-links)]. Its `/v1/admin/sales` routes check only the staff flag \[[ASK-202](https://github.com/snapfix/docs/blob/main/ASK.md#ask-202-does-the-laravel-admin-api-check-tokens-with-the-key-that-authpy-signs-them-with)] ([Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md)).
* The package actions on the server check no staff flag, so any signed-in user can create or delete sales packages, rewrite any paywall schema and read the packages with their prices. The site package route checks none either, so any signed-in user can give any site any package. Who may create packages and take payments is open \[[ASK-205](https://github.com/snapfix/docs/blob/main/ASK.md#ask-205-who-may-take-payments-on-hubspot-deals-and-create-sales-packages-and-payment-links)].

### Card payments

* A card payment creates a package for one site, with a title, a description, a total amount, an interval and a currency; the signed-in user is recorded as creator and salesperson. The server makes the Stripe product and prices and links the package to the site, inactive, for the customer to subscribe to ([Credit card payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/card-payment.md)).
* The form takes an amount of 0 or more, but the server refuses 0 with "invalid amount" \[[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)]. The amount is meant in whole units ("will pay 120 USD per Month"), yet it reaches Stripe as the currency's minor unit, so 120 makes a price of 1.20.
* The interval is "MRR - Monthly Recurring Revenue" (the default) or "ARR - Annual Recurring Revenue". The annual choice is always refused with "invalid interval", so only monthly card payments can be made.
* The currency starts at USD and the list offers every supported currency, but the server takes only USD, EUR, GBP and INR \[[ASK-201](https://github.com/snapfix/docs/blob/main/ASK.md#ask-201-which-currencies-should-the-stripe-package-form-offer)].
* Deleted sites can be picked \[[ASK-223](https://github.com/snapfix/docs/blob/main/ASK.md#ask-223-should-deleted-accounts-be-selectable-for-card-payments-and-support-logs)]; the server refuses them with "invalid parent". After a save the form empties, but the picker still shows the site, so "Save" waits until a site is picked again.

### Stripe packages

* A Stripe package needs a name, one or both payment types ("Card", "SEPA Debit"), a currency and at least one mandatory service; each service row has a name, a price and a recurring type ("Year", "Month", "Daily" or "Non Recurring"), with optional quantities ([Add Package](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md#add-package)).
* "SEPA Debit" needs euro: while it is ticked, every other currency is disabled. The list offers currencies the server refuses, as for card payments \[[ASK-201](https://github.com/snapfix/docs/blob/main/ASK.md#ask-201-which-currencies-should-the-stripe-package-form-offer)].
* A customer may start the package from 30 days before to 30 days after today by default; "Advance Settings" changes the days and the default, start and end dates. The date checks compare text, so ranges across a new year can be judged wrongly.
* Prices are typed in the currency's units and sent multiplied by 100, without rounding. The Stripe path rounds the result; only the bank payment path passes a fraction of a cent on.
* The table's "Active user", "Inactive user" and "Initiated user" columns are always 0. "View Package" opens a read-only copy titled "Edit Package", and shows defaults where 0 is stored.
* "Copy Package URL" copies the package's payment link, a `/multi/` link of the payment app ([Stripe payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md#actions), [Payment links](https://docs.snapfix.com/product/features/billing/payment-links.md)).

### Paywall

* A paywall package belongs to one marketing bundle and is "Core" or "Supplement". It has one price per currency and interval ("Month" or "Year"), and a currency can be used once per interval ([Create Paywall Package](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md#create-paywall-package)).
* Its permissions are a JSON document, the plan limits and switches the apps read. Only values can change; each limit must be at least its warning value, and the dialog names the first break with internal field names. The server checks the schema against a file that is not in the repo \[[ASK-197](https://github.com/snapfix/docs/blob/main/ASK.md#ask-197-is-paywall_schema_v1json-deployed-on-the-api-servers)].
* "Save" sends the built-in default permissions instead of the edited ones when a key differs.
* A package in use opens read-only. A read-only bundle disables adding and editing, with the tooltip "Bundle is readonly" ([Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md#inputs)).
* Each price's "Copy" gives a single-price `/single/` link, whose page cannot take a payment.
* "Update package" on the Parents tab gives a site a package. The app sends no dates, so the server gives it from now for one year and marks the site's other package rows deleted ([Update parent package](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md#update-parent-package), [`PUT /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#put-v4parent-pack)).
* The Parents tab's "Groups" column counts member rows; a page with two or more sites shows 0 jobs and the built-in "Unlimited Package" for each.

### HubSpot deals

* The page lists every deal at once. A deal without a company, a contact or a line item cannot go on, and the message names what Sales must add; a deal with several companies or contacts warns staff to pick the right ones ([Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#actions)).
* Every action needs a chosen company and contact. A company shows at most 20 of its contacts, with a warning from 20 on ([Deal dialog](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#deal-dialog)).
* A payment, a payment or checkout link, a mandate link and an onboarding link need a linked Snapfix site; when the deal has none, staff pick one or create one first ([Create or select an Account](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#create-or-select-an-account), [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md)).
* **Card:** a subscription needs a Stripe customer that is not inactive and at least one line item. Annual and monthly items cannot be mixed, and one-time items alone cannot make a subscription. The start date defaults to the deal's subscription date, then its close date, then today; a future date blocks the payment link until then, unless "Continue" starts it today ([link dialog](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#generate-snapfix-payment-or-stripe-checkout-url)).
* "Generate Snapfix Payment URL" creates a new Stripe package at every press, always with card and SEPA Debit whatever the currency. "Generate Stripe Checkout URL" creates a Stripe checkout session instead; it silently leaves out line items whose product has no Stripe product, and goes on with an empty list when none has one \[[ASK-210](https://github.com/snapfix/docs/blob/main/ASK.md#ask-210-should-a-stripe-checkout-skip-products-that-have-no-stripe-product)]. The start-date warning meant for dates far from the close date never runs.
* **Bank:** each line item is paid one at a time with "Take Payment", once the company has an active or approved mandate; otherwise "Bank Status" opens Mandate Information, whose status line always reads "submitted – not active" ([Mandate Information](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#mandate-information)).
* Charging a line item again asks for a username and password; any staff login passes, not only the signed-in user's \[[ASK-213](https://github.com/snapfix/docs/blob/main/ASK.md#ask-213-should-the-repeat-charge-check-need-the-signed-in-users-own-login)].
* The server charges the customer and mandate the page sends, without tying them to the company, and a failed customer lookup keeps the previous company's customer and statuses.
* "Generate Mandate Request URL" makes a mandate sign-up link for the company's GoCardless customer; without one it does nothing, with no message. Whether a failed mandate lookup should read as "no active mandate" is open \[[ASK-209](https://github.com/snapfix/docs/blob/main/ASK.md#ask-209-should-a-failed-mandate-lookup-show-as-no-active-mandate)].
* The onboarding "Create" makes the deal's setup record and copies its link; it is offered only while the deal has none, so a deal has one ([Onboarding URL](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md#onboarding-url), [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md)).
* A payment link can be made for a site with no site admin, although the Account page asks for one first \[[ASK-212](https://github.com/snapfix/docs/blob/main/ASK.md#ask-212-what-is-an-account-superadmin-and-should-a-payment-link-wait-until-the-site-has-one)].

## Flow

```mermaid
flowchart TD
  start["Staff member opens a billing tool"] --> tool{"Which tool?"}
  tool -- "Credit Card Payment" --> card["Site, title, amount, monthly interval, currency"]
  card --> cardsave["Package for the site, with a Stripe product"]
  tool -- "Stripe Payment" --> stripe["Name, payment types, currency, services"]
  stripe --> link["Copy the package's payment link"]
  tool -- "Paywall" --> bundle["Bundle: packages, prices, permissions"]
  bundle --> parent["Give a site its package for a year"]
  tool -- "Hubspot Deals" --> deal["Pick the company and contact; link a site"]
  deal --> method{"Card or bank?"}
  method -- "card" --> sub["Snapfix payment link or Stripe checkout link"]
  method -- "bank" --> mandate{"Active mandate?"}
  mandate -- "no" --> mi["Mandate Information: send a mandate link"]
  mandate -- "yes" --> pay["Take Payment per line item"]
  deal --> onboard["Onboarding link: the setup form"]
```

## Platforms

| Capability                                                                 | Web                       | iOS | Android |
| -------------------------------------------------------------------------- | ------------------------- | --- | ------- |
| Card payments and Stripe packages                                          | Yes, for listed usernames | No  | No      |
| Paywall bundles, packages and site packages                                | Yes, for listed usernames | No  | No      |
| HubSpot deals: subscriptions, bank payments, mandates and onboarding links | Yes, every staff user     | No  | No      |

## Screens

* [Credit card payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/card-payment.md): a package for one site.
* [Stripe payment](https://docs.snapfix.com/how-the-apps-work/screens/staff/stripe-payment.md): the Stripe packages, with their services and prices.
* [Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md): bundles, paywall packages, permissions and each site's package.
* [Hubspot deals](https://docs.snapfix.com/how-the-apps-work/screens/staff/hubspot-deals.md): the deals, with their payments, links, mandates and onboarding records.

## API and data

* Card payments: [`admin_create_package`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_package), with the site list [`GET /v4/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v4parents) and the currencies from the [Reference API](https://docs.snapfix.com/engineering-reference/api/reference.md).
* Stripe packages: [`admin_read_stripe_products_v3`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_read_stripe_products_v3) and [`admin_create_stripe_product_v3`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_stripe_product_v3) ([Sales package object](https://docs.snapfix.com/engineering-reference/api/staff.md#sales-package-object)).
* Paywall: [`snapfix_bundles`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionsnapfix_bundles), [`snapfix_packages`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionsnapfix_packages), [`create_snapfix_package`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actioncreate_snapfix_package) and [`update_package_schema`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionupdate_package_schema) ([Paywall package object](https://docs.snapfix.com/engineering-reference/api/staff.md#paywall-package-object)); a site's package with [`GET /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#get-v4parent-pack) and [`PUT /v4/parent-pack`](https://docs.snapfix.com/engineering-reference/api/billing.md#put-v4parent-pack).
* HubSpot deals: [`GET /v1/admin/sales/deals`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesdeals), [`GET /v1/admin/sales/deals/{objectId}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesdealsobjectid), [`company-subscriptions`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalescompany-subscriptionscompanyid), [`stripe-customer`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesstripe-customer), [`gocardless-customer`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesgocardless-customer), [`gocardless-payments`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesgocardless-payments), [`gocardless-customer-mandate`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesgocardless-customer-mandate), [`company-gocardless-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-gocardless-checkout), [`company-stripe-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-stripe-checkout) and [`onboarding`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesonboarding); [`POST /v1/admin/parents`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminparents) and [`GET /v1/admin/parents/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminparentsuuid) for the linked site; the repeat-payment login uses `POST /login` ([Auth API](https://docs.snapfix.com/engineering-reference/api/auth.md)).
* Tables: [`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 prices), [`package_server_parent`](https://docs.snapfix.com/engineering-reference/db/tables/package_server_parent.md) (a site's package and period), [`package_marketing_bundle`](https://docs.snapfix.com/engineering-reference/db/tables/package_marketing_bundle.md) (bundles), [`tPri_Org_HubspotDealState`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_hubspotdealstate.md) (deals), [`tPri_Org_StripeCheckoutUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_stripecheckouturllog.md) (checkout and payment links), [`tPri_Org_GoCardlessPaymentLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_gocardlesspaymentlog.md) (bank payments), [`tPri_Org_GoCardlessMandateUrlLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_gocardlessmandateurllog.md) (mandate links) and [`tPri_Org_OnboardingLog`](https://docs.snapfix.com/engineering-reference/db/tables/tpri_org_onboardinglog.md) (onboarding records).

## Depends on

* [Payment links](https://docs.snapfix.com/product/features/billing/payment-links.md) and [Subscriptions](https://docs.snapfix.com/product/features/billing/subscriptions.md): the customer side of the packages, links, subscriptions and plan limits made here.
* [In-app purchase](https://docs.snapfix.com/product/features/billing/in-app-purchase.md): the iOS plans, which also read the packages.
* [Setup form](https://docs.snapfix.com/product/features/onboarding/setup-form.md): what a new customer fills in from the onboarding link.
* [Customer administration](https://docs.snapfix.com/product/features/staff/customer-admin.md): the sites and organizations that packages and deals attach to.
* [Staff admin app](https://docs.snapfix.com/product/features/staff/staff-admin.md): the sign-in and the built-in list.
* Outside services: Stripe (products, prices, checkouts and customers), GoCardless (customers, mandates and payments) and HubSpot (deals, companies and contacts), reached through the org mapping service, which is not in the repos.

## Edge cases

* **Failed lists:** the deal list, the Stripe package list and the site lists show no message, so a failure looks empty; a failed subscriptions load keeps the previous company's rows.
* **Currency list fails:** the paywall create dialog falls back to USD, GBP and EUR ([Paywall](https://docs.snapfix.com/how-the-apps-work/screens/staff/paywall.md#states)).
* **Deleted sites:** they can be picked for a card payment, and the server refuses them \[[ASK-223](https://github.com/snapfix/docs/blob/main/ASK.md#ask-223-should-deleted-accounts-be-selectable-for-card-payments-and-support-logs)].
* **Zero amounts:** the card form passes 0 and the server refuses it; a paywall price of 0 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)].
* **Large lists:** the deals and the Stripe packages each load in one answer, with no paging.
* **Time zones:** none on these pages; dates show as typed or stored.
* **Offline:** not applicable; the admin app is web only.


---

# 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/staff/staff-billing.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.
