Skip to main content
Connect your HubSpot CRM to CommissionKit. The connector syncs owners as sales reps and closed-won deals for commission calculation.

​
How data flows

HubSpot is a CRM, not an ERP — it doesn’t track payments. CommissionKit assigns a default payment status to closed-won deals. You can customize this from the ⋮ menu → Payment Defaults.

​
Stage behavior

HubSpot deal stages are mapped to CommissionKit’s canonical stages: Which deals get synced: the connector auto-discovers your pipeline via HubSpot’s API. By default (syncClosedOnly: true), only deals in stages marked as closed-won are synced. If no stages have isClosed = true, the connector falls back to syncing all deals. Set syncClosedOnly: false in the config to sync every deal regardless of stage.

​
Authentication

CommissionKit uses token-based auth — a single access token from HubSpot. Two ways to get one:

​
Method 1: Service Key

  1. In HubSpot, navigate to Development → Service Keys
  2. Click Create service key, name it “CommissionKit”
  3. Select scopes: crm.objects.owners.read, crm.objects.deals.read, crm.schemas.deals.read
  4. Click Create → copy the token
  5. In CommissionKit, paste it and click Connect

​
Method 2: Legacy App

A Legacy App also provides an access token you can use directly.
  1. In HubSpot, navigate to Development → Legacy Apps
  2. Click Create app → Public app
  3. Fill in the Basic Info tab (name: CommissionKit)
  4. On the Auth tab, set a redirect URL (can be http://localhost for testing) and add scopes:
    • crm.objects.owners.read
    • crm.objects.deals.read
    • crm.schemas.deals.read
  5. Click Create app
  6. Copy the Access Token from the app’s credentials
  7. In CommissionKit, paste it and click Connect
Legacy app credentials (including the access token) are only visible after clicking Create app — not in draft mode.

​
What syncs

​
Required scopes

These three scopes are needed for both Service Keys and Legacy Apps.

​
Sync schedule

After connecting, choose a sync interval from the ⋮ menu:

​
Payment status

CRMs don’t track payments, so CommissionKit assigns a default status to closed-won deals on import. You can change it from the ⋮ menu → Payment Defaults: Deals in non-closed-won stages always import as unpaid regardless of this setting.

​
Troubleshooting

​
”Deal sync shows 0 total”

Check these three things:
  • Deal owner is assigned — deals with no owner are skipped. Open the deal in HubSpot, click the Deal owner dropdown, and assign someone.
  • Sync order matters — sync Reps first, then Deals. The connector needs to pull owners into CKit before it can link deals to them.
  • Stage includes your deal — see Stage behavior above. Verify your deal’s pipeline stage is marked as closed-won in HubSpot, or set syncClosedOnly: false in the connector config to sync all deals.

​
”HTTP 403 — required scopes” or “No stages found”

Your token is missing crm.schemas.deals.read. This scope is required to discover pipeline stages. Go to your Service Key or Legacy App and add it. The three scopes you need are listed in Required scopes above.

​
”0 reps found”

Your token might be missing crm.objects.owners.read. Check your Service Key or Legacy App scopes.

​
”Connection test fails”

  • Service Key: the token starts with pat- — make sure you copied the full value
  • Legacy App: confirm the app was created (not in draft mode). The access token is visible under the app’s credentials after creation
  • Both token types expire — Service Keys have no expiry but Legacy App tokens expire; if you get HTTP 401, regenerate the token in HubSpot and update it in CKit