HubSpot Connection Setup

The HubSpot connection links Flexprice to your HubSpot account through a HubSpot legacy private app. Flexprice uses the app’s access token to read deals and contacts and to create invoices, quotes, and line items in HubSpot. It uses the app’s client secret to verify the deal events that HubSpot sends to Flexprice.

What the HubSpot integration syncs

Sync	Direction	Runs when	Turned on by
Customer sync	HubSpot to Flexprice	A deal moves to Closed won, or a deal is created	The deal webhook subscriptions in your HubSpot app
Quote sync	Flexprice to HubSpot	A subscription is created as a draft	The Quotes toggle
Deal sync	Flexprice to HubSpot	A subscription is created, or its quantities or add-ons change	The Deals toggle
Invoice sync	Flexprice to HubSpot	An invoice is finalized	The Invoices toggle

Flexprice does not sync payments, plans, or prices with HubSpot, and it does not read invoices back from HubSpot.

Before you connect HubSpot

HubSpot super admin access. HubSpot only lets super admins create private apps.
The Flexprice environment for the connection. The webhook URL that HubSpot calls contains the tenant and environment IDs of that environment, so create the connection in the environment you want customers to land in.
A HubSpot quote template, if you plan to use quote sync. HubSpot only publishes quotes that have a template, and Flexprice attaches the first template in your account.

Step 1: Create a HubSpot legacy private app

Open legacy apps in HubSpot

In your HubSpot account, go to Development, then click Legacy apps in the left sidebar.The page encourages you to build new apps on HubSpot’s newer developer platform instead. Create a legacy app anyway: the Flexprice connection uses a legacy private app’s access token and client secret.

Create a private app

Click Create legacy app, then select Private. On the Basic info tab, enter a name such as Flexprice.

Add the scopes

On the Scopes tab, click Add new scope and select the scopes for the syncs you plan to use, listed in the table below. Click Update.

Create the app

Click Create app, review the notice about the access token, then click Continue creating.

HubSpot scopes for each Flexprice sync

Sync	Scopes
Every connection	`crm.objects.contacts.read`, `crm.objects.contacts.write`
Customer sync	`crm.objects.deals.read`
Invoice sync	`crm.objects.invoices.read`, `crm.objects.invoices.write`, `crm.schemas.invoices.read`, `crm.schemas.invoices.write`, `crm.objects.line_items.read`, `crm.objects.line_items.write`
Deal sync	`crm.objects.deals.read`, `crm.objects.deals.write`, `crm.schemas.deals.read`, `crm.schemas.deals.write`, `crm.objects.line_items.read`, `crm.objects.line_items.write`
Quote sync	`crm.objects.quotes.read`, `crm.objects.quotes.write`, `crm.schemas.quotes.read`, `crm.schemas.quotes.write`, `crm.objects.line_items.read`, `crm.objects.line_items.write`

The Connect HubSpot sheet in Flexprice only reminds you to create a private app with the CRM contacts, line items, deals, and quotes scopes. Use the table above for the exact scopes each sync needs. Customer sync needs crm.objects.deals.read even when deal sync is off, to read each deal and its contacts. HubSpot prompts you to add it when you subscribe to deal events in Step 4.

Step 2: Copy the HubSpot access token and client secret

Open your app from Development → Legacy apps, then click the Auth tab.

Credential	Where to find it	What Flexprice uses it for
Access token	Click Show token, then Copy. The token starts with `pat-`.	Every API call Flexprice makes to HubSpot
Client secret	Click Show secret.	Verifying the `X-HubSpot-Signature-v3` header on the deal events HubSpot sends

Auth tab of the Flexprice legacy app in HubSpot, with the masked access token and client secret and their Show and Copy buttons

Step 3: Create the HubSpot connection in Flexprice

Connecting HubSpot from the Flexprice dashboard

Open the HubSpot integration

In the Flexprice dashboard, open Integrations and click Connect on the HubSpot card.

Enter the credentials

Fill in Connection name, then paste the Private app access token and Client secret from Step 2. Click Continue.

Connect HubSpot sheet on the Credentials step with the connection name, masked access token, and client secret

Choose what Flexprice pushes to HubSpot

On the Sync step, turn on Push invoices, Push deals, and Push quotes for the syncs you want. All three are off by default. Click Continue.

Sync step with the Push invoices, Push deals, and Push quotes switches

Copy the webhook URL

The Webhook step shows the webhook URL and the deal event HubSpot needs to send. Click the copy icon next to Webhook URL: you paste it into HubSpot in Step 4.

Save the connection

Click Connect HubSpot. The HubSpot card moves under Connected on the Integrations page.

Integrations page with the HubSpot card under Connected

Creating the HubSpot connection with the API

curl -X POST https://api.cloud.flexprice.io/v1/connections \
  -H "x-api-key: <API_KEY>" \
  -H "X-Environment-ID: <ENVIRONMENT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "HubSpot Production",
    "provider_type": "hubspot",
    "encrypted_secret_data": {
      "access_token": "pat-na1-...",
      "client_secret": "<CLIENT_SECRET>"
    },
    "sync_config": {
      "invoice": { "inbound": false, "outbound": true },
      "deal": { "inbound": false, "outbound": true },
      "quote": { "inbound": false, "outbound": true }
    }
  }'

Field	Required	Description
`provider_type`	Yes	Always `hubspot`
`encrypted_secret_data.access_token`	Yes	The private app’s access token. Flexprice encrypts it at rest.
`encrypted_secret_data.client_secret`	Yes	The private app’s client secret. Flexprice encrypts it at rest.
`sync_config.invoice.outbound`	No	Push finalized invoices to HubSpot
`sync_config.deal.outbound`	No	Push subscription line items to the customer’s HubSpot deal
`sync_config.quote.outbound`	No	Create a HubSpot quote for each draft subscription

If you leave out sync_config, every sync is off. Deals and quotes only sync outbound, so Flexprice rejects inbound: true for either of them. Customer sync starts when HubSpot sends a deal event to Flexprice. Set this up in the same private app:

Open the webhook settings

In HubSpot, open your app, click Edit app in the top right, then open the Webhooks tab.

Set the target URL

Under Target URL, paste the webhook URL you copied in Step 3. It has this format:

https://api.cloud.flexprice.io/v1/webhooks/hubspot/<tenant_id>/<environment_id>

Copy it from the connection drawer rather than typing it, because the host depends on your Flexprice region. HubSpot already shows https:// in front of the field, so paste the rest of the URL after it.

Subscribe to deal stage changes

Click Create subscription. In the panel, choose Deal under Which object types?, Property changed under Listen for which events?, and dealstage under Which properties?. Click Subscribe.Leave Use expanded object support? off. It switches HubSpot to generic event types, and Flexprice only reads deal.propertyChange and deal.creation.

Commit the changes

The subscription appears under Event subscriptions as dealstage changed, with the subscription type deal.propertyChange. Click Commit changes in the top right.

HubSpot deal events Flexprice handles

HubSpot subscription	Event type	What Flexprice does
Deal, Property changed, dealstage	`deal.propertyChange` on `dealstage`	Imports the deal’s contacts as customers when the stage changes to `closedwon`. Other stage changes are ignored.
Deal, Created (optional)	`deal.creation`	Imports the deal’s contacts as soon as the deal is created, before it is won.

The connection drawer asks for the deal stage subscription only. Add the Created subscription if you want customers in Flexprice for every new deal, not only for won deals.

Flexprice matches the stage whose internal value is closedwon, which is the Closed won stage of HubSpot’s default sales pipeline. Deals that close in other pipelines have different stage IDs, so Flexprice does not import their contacts.

Flexprice answers every request from HubSpot with 200 OK, including requests it ignores or rejects, so HubSpot never retries them. A passing Test in HubSpot’s webhook panel only shows that the URL is reachable. To confirm that deal events are processed, close a test deal and check that its contacts appear as customers in Flexprice.

Changing HubSpot connection settings and credentials

To change the connection name or turn syncs on or off, open Integrations in the Flexprice dashboard and click Configure on the HubSpot card. The settings sheet does not show the access token or client secret.

HubSpot connection settings with the connection name, sync switches, webhook, and Disconnect, but no access token or client secret fields

To use a new access token or client secret, click Disconnect HubSpot in the same sheet, then connect HubSpot again with the new values. Links between Flexprice customers and HubSpot contacts, invoices, and line items are stored separately from the connection, so they are kept.

When you rotate the access token in HubSpot, choose Rotate and expire later. The old token keeps working for 7 days, which gives you time to recreate the connection before it expires.

Troubleshooting the HubSpot connection

Issue	Cause	Solution
No customers appear after a deal is won	The webhook subscription is missing or paused, or its target URL points at another environment	On the app’s Webhooks tab, check the subscription and the target URL. The tenant and environment IDs in the URL must belong to the environment that has the connection.
HubSpot shows successful deliveries, but no customers appear	The client secret in Flexprice does not match the app’s client secret, so Flexprice discards the requests	Recreate the connection with the secret from the app’s Auth tab
Contacts of deals won in a custom pipeline are not imported	Flexprice only recognises the `closedwon` stage of the default sales pipeline	Use the default sales pipeline for these deals, or add the Created deal subscription
Invoices, deals, or quotes do not appear in HubSpot	The sync toggle is off, or the app is missing scopes	Turn on the toggle on the connection and add the scopes from Step 1
Every HubSpot call starts failing	The access token was rotated or expired	Recreate the connection with the current token

To see what HubSpot sent and how Flexprice responded, open your app in HubSpot, click the Logs tab, then click Webhooks.

HubSpot sync guides

Customer sync

How contacts on HubSpot deals become Flexprice customers.

Quote sync

How draft subscriptions become draft HubSpot quotes.

Deal sync

How subscription line items and the deal amount reach the HubSpot deal.

Invoice sync

How finalized invoices are pushed to HubSpot.

​What the HubSpot integration syncs

​Before you connect HubSpot

​Step 1: Create a HubSpot legacy private app

​HubSpot scopes for each Flexprice sync

​Step 2: Copy the HubSpot access token and client secret

​Step 3: Create the HubSpot connection in Flexprice

​Connecting HubSpot from the Flexprice dashboard

​Creating the HubSpot connection with the API

​Step 4: Subscribe HubSpot to deal events

​HubSpot deal events Flexprice handles

​Changing HubSpot connection settings and credentials

​Troubleshooting the HubSpot connection

​HubSpot sync guides

Customer sync

Quote sync

Deal sync

Invoice sync

What the HubSpot integration syncs

Before you connect HubSpot

Step 1: Create a HubSpot legacy private app

HubSpot scopes for each Flexprice sync

Step 2: Copy the HubSpot access token and client secret

Step 3: Create the HubSpot connection in Flexprice

Connecting HubSpot from the Flexprice dashboard

Creating the HubSpot connection with the API

Step 4: Subscribe HubSpot to deal events

HubSpot deal events Flexprice handles

Changing HubSpot connection settings and credentials

Troubleshooting the HubSpot connection

HubSpot sync guides