> 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/hubspot-deals.md).

# Hubspot deals

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

Staff work through the HubSpot deals from Sales. For one deal they pick the company and the contact, link the Snapfix site, then create a card subscription or a checkout link, take bank payments, send a mandate link, or create the onboarding link for a new customer.

* **Where:** admin app `/hubspot-deals`; menu "Hubspot Deals", shown to every staff user, unlike the other payment pages
* **Who:** anyone signed in to the admin app ([Access](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#access)). The `/v1/admin` routes behind it 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)]; the payment package action checks none.
* **Feature:** [Billing setup](https://docs.snapfix.com/product/features/staff/staff-billing.md)

## Layout

1. **Title row.** "Hubspot Deals", and "Add/Remove columns" with its "Show Columns" list.
2. **Table.** Every deal at once, 10 rows per page by default (10, 20, 50 or 100), with a quick jump box. Columns: "Object Id" (hidden at first; search box), "Deal Name" (search box), "Amount", "Currency", "Checkout URLs Generated" (how many links the deal has), "Closed Date" (sorted newest first at the start), "Created Date" and "Action" (a round "View" button). The amount, currency, count and date columns sort; dates show as `YYYY-MM-DD`.

## Inputs

| Field                              | Type                             | Required | Default  | Rules and messages                                                                                                                                                    |
| ---------------------------------- | -------------------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Object Id search, Deal Name search | Text, in the column's search box | No       | Empty    | Keep the loaded deals whose value contains the text, ignoring case. A new search clears the other column's search. Rows with no value are kept while a search is set. |
| Columns                            | Checkboxes, under "Show Columns" | No       | As above | Applies at once.                                                                                                                                                      |

## Actions

| Action        | Who              | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | API                                                                                                                                 |
| ------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Open the page | Anyone signed in | Loads every deal in one answer, with no paging on the server.                                                                                                                                                                                                                                                                                                                                                                                                                                                         | [`GET /v1/admin/sales/deals`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesdeals)                    |
| View          | Anyone signed in | Loads the deal with its companies, contacts, line items and links, and opens the [deal dialog](#deal-dialog). The button spins and the other "View" buttons are disabled meanwhile. "Deal details not found" when there is no deal; for a deal without a company, contact or line item, a 10-second message instead: "It looks like Sales have not included a company with this deal. Go back to sales and request they include a company, contact and one or more line items in the deal.", naming the missing part. | [`GET /v1/admin/sales/deals/{objectId}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesdealsobjectid) |

## States

* **Loading:** the table shows its spinner while the deals load.
* **Empty:** no deals, no rows.
* **Error:** a failed deal list shows no message and leaves the table empty.
* **No permission:** none in the app.

## Dialogs and sheets

### Deal dialog

Titled "ID: " and the deal's ID; no footer, and neither a click outside nor Escape closes it. From top to bottom:

1. **Header.** "Deal:" and the deal's name; "Snapfix Account:" and the site's name once a site is linked; "Created:", "Closed:" and "Subscription:" dates, the last `<unspecified>` when empty.
2. **Company.** A radio list of the deal's companies: name, country, state, city and website.
3. **Company Contacts.** A radio list of the chosen company's contacts, billing contacts first, at most 20.
4. **Deal Contacts.** A radio list of the deal's contacts. Each contact shows the first and last name, email and phone.
5. **Status.** Two radios, "Card Status:" and "Bank Status:", each with "Active", "Inactive" or "-".
6. **History.** Card: "Subscriptions:" ("Start", "End", "Currency") and "Checkout / Payment URLs:" ("Url", "Date"). Bank: "Line Item Payments:" ("Description", "Date", "Amount") and "Bank Mandate Request URLs:". Each link has a copy button.
7. **Line Items.** "Name" (an information popover with the default and actual amounts, the price items and the description), "Qty", "Price", "Disc", "Net" and "Type" (annual, monthly or one time). Card: a checkbox per item. Bank: an expand arrow listing the item's payments ("No bank payments" when none) and a "Take Payment" button.
8. **Create New Subscription.** Card only: "Create", or "Card payment not active" when a company and a contact are chosen and their Stripe customer is inactive.
9. **Onboarding URL.** "Create New Onboarding URL:" with "Create" while the deal has no onboarding record (enabled once a company and a contact are chosen), then "Onboarding URL:" with "View". Once the customer has finished, "Onboard completed:" with the date and time (`YYYY-MM-dd HH:mm`) and no button.

| Field                     | Type                            | Required                         | Default | Rules and messages                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------------- | ------------------------------- | -------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Company                   | Radio                           | Yes, for every action but "View" | None    | Choosing one loads its subscriptions and the GoCardless payments of the deal's line items, and shows its links. With 20 contacts or more, a warning: "This company has an unusually large number of contacts. Only the first 20 Company contacts are displayed, which may not include the contact you need. For this Deal, please rely on the Deal contacts list instead. If you're uncertain about which contact to use, consult the Account Executive who created the Deal in HubSpot". |
| Contact                   | Radio, from either contact list | Yes, for every action but "View" | None    | With a company, loads the Stripe and GoCardless customers and sets the two statuses; the radios are disabled and the statuses show "-" meanwhile. A failed or empty lookup keeps the previous company's customer and status.                                                                                                                                                                                                                                                              |
| Card Status / Bank Status | Radio                           | No                               | Card    | Choosing "Bank Status" while the bank status is not active opens [Mandate Information](#mandate-information) and switches back to card.                                                                                                                                                                                                                                                                                                                                                   |
| Line items (card)         | Checkboxes                      | At least one, for "Create"       | None    | Annual and monthly items cannot be mixed: ticking one kind disables the other, with the tooltip "A subscription can contain annual or monthly line items, but is cannot contain a mixture of both."                                                                                                                                                                                                                                                                                       |

| Action                  | Who              | What happens                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | API                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Choose a company        | Anyone signed in | As above. A failed subscriptions load keeps the previous company's list, with no message.                                                                                                                                                                                                                                                                                                                                                                                    | [`GET /v1/admin/sales/company-subscriptions/{companyId}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalescompany-subscriptionscompanyid), [`POST /v1/admin/sales/gocardless-payments`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesgocardless-payments) |
| Choose a contact        | Anyone signed in | As above; a failed lookup shows the server's message.                                                                                                                                                                                                                                                                                                                                                                                                                        | [`GET /v1/admin/sales/stripe-customer`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesstripe-customer), [`GET /v1/admin/sales/gocardless-customer`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminsalesgocardless-customer)                                    |
| "Create" (subscription) | Anyone signed in | Needs a company, a contact, a Stripe customer that is not inactive, and a line item. For one-time items only, an "Error": "You can have a mixture of recurring and one time line items in a subscription but you cannot create a subscription with just one time line item(s)." Otherwise asks for a site when none is linked ([Create or select an Account](#create-or-select-an-account)), then opens [the link dialog](#generate-snapfix-payment-or-stripe-checkout-url). | None to open                                                                                                                                                                                                                                                                                                          |
| "Take Payment"          | Anyone signed in | Charges that line item to the company's bank mandate, after asking for a site when none is linked; when the item has earlier payments, [a login](#warning-repeat-bank-payment) comes first. "Success" when it works. The server does not tie the customer and mandate to the company.                                                                                                                                                                                        | [`POST /v1/admin/sales/company-gocardless-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-gocardless-checkout)                                                                                                                                                        |
| Onboarding "Create"     | Anyone signed in | After asking for a site when none is linked, creates the onboarding record, copies its link a second later ("Onboarding URL copied to Clipboard") and opens [Onboarding URL](#onboarding-url). When the copy fails, the message points to the Checkout URLs list and ends with a stray quote. The customer's side is the [setup form](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/setup-form.md).                                                          | [`POST /v1/admin/sales/onboarding`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesonboarding)                                                                                                                                                                                          |
| Onboarding "View"       | Anyone signed in | Opens [Onboarding URL](#onboarding-url).                                                                                                                                                                                                                                                                                                                                                                                                                                     | None                                                                                                                                                                                                                                                                                                                  |

When the deal has more than one company or contact, a "Warning" opens a second after the dialog: "The sales team have included more than one company/contact. Make sure you choose the correct company and contact for this subscription." with "Close".

### Generate Snapfix Payment OR Stripe Checkout URL

Opened by "Create".

| Field      | Type      | Required | Default                                                       | Rules and messages                                                                                                       |
| ---------- | --------- | -------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Start Date | Date      | Yes      | The deal's subscription date, else its close date, else today | Without it both buttons are disabled. A check meant to warn about a date far from the close date returns before it runs. |
| Frequency  | Read-only | —        | The chosen items' frequencies, joined with " / "              | "-" when none.                                                                                                           |

The text "Click here to generate a Snapfix / Stripe Payment URL with full Snapfix branding and connection back to our Snapfix Account:" stands above "Generate Snapfix Payment URL", then "OR", then "In exceptional cases, when we don't want to require the creation or login to an account we can send a generic Stripe Checkout URL:" above "Generate Stripe Checkout URL".

* **Generate Snapfix Payment URL** creates a new Stripe package for the deal's line items, with the company, the contact, the Stripe customer and the site, at every press ([`POST ?action=admin_create_stripe_product_v3`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-actionadmin_create_stripe_product_v3)). The package always offers card and SEPA Debit, whatever the currency.
* **Generate Stripe Checkout URL** creates a Stripe checkout session for the company and the chosen items ([`POST /v1/admin/sales/company-stripe-checkout`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalescompany-stripe-checkout)).
* Either link joins the list and is copied a second later, with "Payment URL copied to Clipboard" or "Checkout URL copied to Clipboard"; when the copy fails, the message asks for the copy button in the list.
* With a start date in the future, a "Warning" comes first: "This subscription is scheduled to start on {date} (in {N days, or N hours}). A payment link cannot be generated until that date." and "If you'd like to start the subscription immediately, press Continue. Otherwise, click Cancel and return to this screen on {date}, to generate the payment link.", with "Continue", which uses today, and "Cancle".

### Create or select an Account

Opened when the deal has no linked site, by "Create", "Take Payment", the onboarding "Create" and "Generate Mandate Request URL". Titled "Create or select an Account", or "Create or select an account to generate an onboarding URL". It shows the deal and company names, then "Choose an Account using the dropdown. If an Account does not exist then create one" when the deal allows a new site, or "Sales have indicated an Account already exists for this Hubspot Company/Deal. Please choose it from the dropdown below."

* "Select Snapfix Account", the [account picker](https://docs.snapfix.com/how-the-apps-work/screens/staff.md#account-picker): picking a site links it to the deal and closes the dialog.
* "Create Account" opens [Add Account](https://docs.snapfix.com/how-the-apps-work/screens/staff/accounts.md#add-account-and-edit-account) with the deal's name and the company's address, state, city and country; when it saves, the new site is linked.

### Warning (repeat bank payment)

Opened by "Take Payment" for an item already paid: "We have already received payment for this line item. If you want to re-charge for this line item enter your username and password to verify".

| Field    | Type                         | Required | Default | Rules and messages           |
| -------- | ---------------------------- | -------- | ------- | ---------------------------- |
| Username | Text                         | Yes      | Empty   | "Please input your username" |
| Password | Password, with a show button | Yes      | Empty   | "Please input your password" |

"Continue", disabled until both are filled, signs in with them ([`POST /login`](https://docs.snapfix.com/engineering-reference/api/auth.md)). A refused sign-in shows the server's message; an account without the staff flag gets "The username or password is invalid."; any other staff login passes, not only the signed-in user's, and the session does not change \[[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)]. Then the payment starts. "Cancel" closes it.

### Mandate Information

Opened by "Bank Status" while the bank status is not active. The text: "An active/approved bank mandate must be in place before you can apply bank payments to individual line items. Please note that bank payments work differently than card payments. With bank payments, you click on each line item one at a time and apply it as a one off or recurring bank payment." Then "Company:" and its name, "Mandate status:" with the fixed text "submitted – not active", "Existing Mandate Request URLs:" with each link, its date and a copy button, and "Existing Mandates:" ("Date", "Status", "Comment").

"Generate Mandate Request URL" asks for a site when none is linked, creates a mandate request link for the company's GoCardless customer, lists it and copies it ("Mandate URL copied to Clipboard") ([`POST /v1/admin/sales/gocardless-customer-mandate`](https://docs.snapfix.com/engineering-reference/api/staff.md#post-v1adminsalesgocardless-customer-mandate)). Without a GoCardless customer it does nothing, with no message.

### Onboarding URL

"Url" (the setup form's address for this record, with a copy button), "Deal", "Account", "Address", "State", "Postal Code", "City" and "Country" (named from the site's country code), and "Close". It loads the site when it was not loaded yet, and the country list ([`GET /v1/admin/parents/{uuid}`](https://docs.snapfix.com/engineering-reference/api/staff.md#get-v1adminparentsuuid), [`GET ?action=countries_list`](https://docs.snapfix.com/engineering-reference/api/reference.md)).


---

# 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/hubspot-deals.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.
