> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numeral.com/llms.txt
> Use this file to discover all available pages before exploring further.
# HubSpot
> Real-time sales tax on HubSpot deals, quotes, and invoices, with finalized invoices recorded for filing.
This guide takes you from nothing to a working HubSpot connection. By the end, Numeral will be calculating sales tax on your deals in real time (as a **Sales Tax** line item your customers see on quotes and invoices), and recording your finalized invoices for US sales tax filings. Setup takes about 15 minutes and you verify each step as you go.
Numeral writes exactly one thing into HubSpot: the Sales Tax line item. Everything else is read-only — the full list of what the app can access is in [What Numeral accesses](#what-numeral-accesses) below.
***
## Before you start
Work through this checklist; each item is needed by a later step:
* A **Numeral account** with admin access
* You are a **Super Admin** in the HubSpot portal you want to connect (HubSpot requires this to install apps)
* **Invoices are enabled** in HubSpot if you bill from HubSpot (Settings → Objects → Invoices)
* Your deals' **associated company records carry a full US address** (street, city, state, ZIP) — this address determines the taxing jurisdiction, and deals without it are skipped
***
## Step 1 — Connect your HubSpot portal
1. In **Numeral**, go to **Connections** in the left navigation
2. Click **Add a Connection**
3. Find and click the **HubSpot** card
4. Enter a **Connection Name** (anything that helps you recognize the portal later), then click **Continue**
5. Your browser goes to HubSpot. If you belong to several HubSpot accounts, an **account chooser** appears — pick the portal you want to connect
6. Review the consent screen and click **Connect app**. If this portal authorized Numeral before, HubSpot skips the consent screen and shows "previously authorized, redirecting" — that is normal
You should now be back on the Numeral Connections page, with your HubSpot connection showing as connected. If you hit an error instead, jump to [Troubleshooting](#troubleshooting).
**Installing from the HubSpot marketplace instead**
If you start from the app's HubSpot marketplace listing, the order flips: HubSpot authorizes first, then you sign in to Numeral and see a confirmation — "Connect HubSpot portal X to \[account]?" — before anything is created. Check the account name on that screen; the portal attaches to whichever Numeral account you confirm. Both paths end at the same connected state.
***
## Step 2 — Add the Numeral cards in HubSpot
HubSpot never shows app cards automatically; you add each card once, and it then appears for everyone in the portal.
### Deal card
The deal card shows the tax total, a jurisdiction-by-jurisdiction table, and a Recalculate button.
1. Open any **deal record** in HubSpot
2. In the middle column, click **Customize tabs** (also reachable via Settings → Objects → Deals → Record customization)
3. Pick a tab (or add one), click **Add cards**, and select **Numeral Sales Tax** under Apps
4. **Save**
### Invoice card
The invoice card shows when an invoice has been recorded for filing.
Invoices have no full record pages in HubSpot, so this card lives in the **invoice preview panel**.
1. Open any record with an invoice (deal, contact, or company), find the invoice in the **Invoices** card in the right sidebar, and click it to open the **preview**
2. In the preview, click the **gear icon in the "About this invoice" section**
3. Add the **Numeral Sales Tax (Invoices)** card and save
You should now see the Numeral Sales Tax card on deal records (it reads "No tax calculated yet" until Step 3) and the invoices card in the preview panel.
**Where the invoice card is NOT**
The slide-in from the Commerce → Invoices list is HubSpot's own invoice viewer and cannot hold app cards. Use the invoice preview from a record's Invoices sidebar instead.
***
## Step 3 — Verify with a test deal
This is the proof the connection works end to end.
1. In HubSpot, create a **new deal** (any pipeline)
2. Associate a **company that has a complete US address**
3. In the deal's **Line items** section, add one or two products with prices
4. Wait a few seconds and refresh the deal
A "Sales Tax" line item should appear among the deal's line items, and the Numeral Sales Tax card should show the total with a jurisdiction breakdown (for a California address: a California row and a city or county row). Edit a line item's price and watch both update.
Optional, if you bill from HubSpot: create an invoice from this test deal (it inherits the line items including Sales Tax), add a billing contact, and **Finalize** it. Within a minute its preview card shows **Committed for filing**. Because Test mode is on (next step), this stays on your test environment and touches no filings — delete the test records when you are done.
If no Sales Tax line appears, the fix is almost always the company address — see [Troubleshooting](#troubleshooting).
***
## Step 4 — Review your settings
Open the app's settings in HubSpot: **Settings (gear) → Integrations → Connected apps → Numeral Sales Tax → Settings tab**.
| Setting | What it does |
| - | - |
| **Test mode** | On by default. While on, calculations and recorded invoices stay on your Numeral test environment and are excluded from filings. Leave it **on** until your Numeral onboarding contact confirms go-live; changes apply from the next calculation. |
| **Tax line display** | **Combined** (default) writes one "Sales Tax" line per deal. **By jurisdiction** writes one line per jurisdiction — "Sales Tax - California", "Sales Tax - San Francisco" — always summing exactly to the total. Switching rewrites each deal's lines on its next calculation. |
Setup is complete. From here, tax appears on deals automatically, finalized invoices are recorded for filing, and your invoice history imports in the background. The sections below are reference.
***
## What Numeral accesses
The consent screen in Step 1 lists these scopes:
| Data | Access | Why we need it |
| - | - | - |
| Deals and line items | Read and write | Calculate tax when line items change; create and update the Sales Tax line item (the only thing Numeral ever writes) |
| Quotes | Read and write | Refresh the deal's tax when a quote is created so the quote snapshots the right amount |
| Invoices | Read | Record finalized and paid invoices for filing |
| Payments | Read | Reconcile invoice payments at filing time |
| Products | Read | Keep your product catalog in Numeral for tax categorization |
| Companies and contacts | Read | Use the customer's address to determine the taxing jurisdiction |
Your OAuth tokens are stored encrypted. Numeral never modifies your deals beyond the Sales Tax line item, and never deletes anything you created.
***
## How the integration works
**On deals:** when line items change, Numeral waits a few seconds for the burst of edits to settle, calculates once from the associated company's address, and creates or updates the **Sales Tax** line in place. The Sales Tax line is excluded from its own calculation; unpriced products are skipped; if nothing taxable remains, the line is removed. Deleting the line by hand is safe — it is restored on the next change or Recalculate.
**On quotes:** creating a quote refreshes the deal's tax first, so the quote's snapshot includes the current Sales Tax line.
**On invoices:** invoices created from a deal inherit its line items, including the Sales Tax line. When an invoice reaches **Open** (finalized) or **Paid**, Numeral records it for filing exactly once — marking it paid later, or delivery retries, never double-record it. Drafts are never recorded; voids and refunds after recording are reconciled by the background sync.
**In the background:** the product catalog syncs at connect time and stays current; your invoice history imports so prior periods can be filed; a safety sweep retries any invoice whose recording failed transiently, so nothing is silently lost.
**At filing time:** Numeral aggregates your HubSpot sales for the period and prepares the return for review on the **Filings** page.
***
## Troubleshooting
In order of likelihood:
1. The deal has **no associated company**, or the company's address is incomplete — a ZIP code, or city plus state, is the minimum. Fix the address, then edit any line item (or click **Recalculate** on the card).
2. The deal has **no priced line items** — items without a price are skipped.
3. The connection is disconnected or broken — check the Numeral **Connections** page.
It should update within seconds of any change. If it does not, open the deal's Numeral card and click **Recalculate**.
It is restored automatically on the deal's next change, or immediately via **Recalculate**.
The card keeps the last good amounts, and the message says what went wrong — most often a missing or unusable address. Fix the cause and click **Recalculate**.
The card could not reach Numeral. Retry; if it persists, check the connection on the Numeral Connections page and contact support.
Only **Open** or **Paid** invoices are recorded — drafts are not. If a finalized invoice still is not recorded after a few minutes, an automatic retry runs within the hour; if it still is not, contact support with the invoice number.
Disconnect from the Numeral Connections page, then connect again and pick the right portal at HubSpot's account chooser. A portal can only be attached to one Numeral account at a time.
On the Numeral **Connections** page, click into the HubSpot connection and use **Disconnect**. Numeral uninstalls the app from your portal (HubSpot emails your super admins a confirmation), removing the cards and stopping all syncing. Sales Tax lines already on deals stay as they are. Your historical filing data is preserved.