HubSpot setup guide

PayClarity is a HubSpot-native commission platform. After you install and authorize the app, PayClarity syncs deals, owners, pipelines, and line items from your HubSpot CRM, calculates commission lines from your rules, and can write commission totals back to custom deal properties in HubSpot.

This guide is public — you do not need a PayClarity account to read it. Use it to understand the full user journey before installing from the HubSpot Marketplace or from payclarity.io/login.

• Typical setup time: 10–20 minutes
• Any HubSpot user who can install marketplace apps may connect the portal
• No custom code required — OAuth + guided onboarding wizard

• A HubSpot account with Sales Hub or CRM access to deals, pipelines, and owners
• Permission to install apps on your HubSpot portal (marketplace or OAuth consent)
• Deals organized in one or more pipelines you want to commission on
• Modern browser; PayClarity runs at payclarity.io

There are two common ways to start:

Path A — Install from HubSpot Marketplace (recommended)

1. Open the HubSpot Marketplace and search for PayClarity.
2. Click Install app and choose the HubSpot portal (account) to connect.
3. You are redirected to HubSpot OAuth, then back to PayClarity to create your workspace and start onboarding.

Path B — Sign in from PayClarity first

1. Go to /signup or /login.
2. Click Login with HubSpot (OAuth). This binds your PayClarity workspace to your HubSpot portal_id.
3. Complete the onboarding wizard described below.

Step 2

PayClarity uses standard HubSpot OAuth 2.0. After you approve access, tokens are stored securely per workspace and refreshed automatically. The OAuth redirect URL registered for production is:

https://payclarity.io/api/auth/hubspot

Required OAuth scopes

Full scope list in app config: oauth, crm.objects.companies.read, crm.objects.contacts.read, crm.objects.deals.read, crm.objects.deals.write, crm.objects.owners.read, crm.schemas.deals.read, crm.schemas.deals.write

Deal properties created automatically

On first install, PayClarity creates these read-only custom deal properties in your HubSpot portal (you do not create them manually):

• commission_total — Commission Total
• commission_status — Commission Status
• commission_breakdown — Commission Breakdown
• commission_rate — Commission Rate
• commission_rule — Commission Rule

After OAuth, new workspaces are guided through an 8-step onboarding wizard at /onboarding. You can re-run it later from Settings → Re-run setup wizard.

1. Welcome — overview of the guided setup
2. HubSpot — confirm CRM connection (or Sign in with HubSpot)
3. Users — invite teammates from your HubSpot user list
4. Pipelines — choose which deal pipelines generate commissions
5. Commission — who earns (owner, owner+SDR, multi-split)
6. First rule — pick a template and name
7. Rule details — rates, conditions, splits, scope
8. Launch — review; PayClarity runs initial owner sync, deal sync, and commission calculation

PayClarity reads your existing CRM structure. Before or after install, ensure:

• Deal pipelines & stages reflect your sales process (PayClarity does not create pipelines)
• Deal owners are assigned on deals you expect to commission
• Amounts (and line items, if used in rules) are accurate on closed or payable stages
• Optional: set your HubSpot fiscal year if you use fiscal reporting in PayClarity settings

You do not need to configure webhooks in the HubSpot CRM UI — deal webhooks are registered on the PayClarity developer app for real-time updates after install.

After onboarding, verify data in PayClarity:

1. Open Dashboard → Deals to see synced HubSpot deals and commission status.
2. If deals are missing, go to Settings and run Full HubSpot Sync.
3. Build or edit rules under Rules; changes recalculate commission lines on matching deals.
4. Use Reports and Payouts for approvals and payroll-ready exports.

HubSpot setup is complete once deals sync and commissions calculate. If you pay commissions only when cash is collected, you can later connect QuickBooks Online, Xero, Zoho Books, or FreshBooks under Dashboard → Integrations to map payments to HubSpot deals. That step is independent of the HubSpot OAuth flow described here.

View all integrations →

“You are not invited to this workspace”

After the first user connects a portal, additional PayClarity users need an email invite from a workspace admin — or must sign in with a PayClarity account already linked to that workspace.

OAuth scope mismatch error

The scopes in the install URL must exactly match the PayClarity app in the HubSpot developer account. If you self-host PayClarity, align HUBSPOT_OAUTH_SCOPES with your app config.

No pipelines in onboarding

Click Sync HubSpot & reload pipelines on the Pipelines step, or run Full HubSpot Sync in Settings, then refresh the wizard.

Token expired / wrong portal

Settings → Reconnect HubSpot (/api/auth/hubspot?force=1). Ensure you authorize the same HubSpot portal as your workspace.

Commissions not updating on deal changes

Run Full HubSpot Sync. Confirm the deal is in a selected pipeline and matches an active rule. Deal webhooks process updates within minutes under normal conditions.

More answers: FAQ

Email connect@payclarity.io for install help, marketplace listing questions, or partner onboarding.

Signed-in users can also open in-app support from the dashboard Help center.