Intermediate
How to integrate product usage data on HubSpot
Quick Answer
Integrate product usage data into HubSpot by creating custom properties, setting up data sync through HubSpot's API or third-party connectors, and configuring automated workflows. This enables you to track user engagement, trigger targeted campaigns, and improve customer success initiatives based on actual product behavior.
Prerequisites
- HubSpot Professional or Enterprise subscription
- Admin access to HubSpot account
- Access to your product's database or analytics platform
- Basic understanding of APIs and data mapping
1
Create Custom Properties for Usage Data
Navigate to Settings > Properties in your HubSpot account. Click Create property and select the appropriate object type (Contact, Company, or Deal). Create properties for key usage metrics such as:
- Last login date (Date picker)
- Feature usage count (Number)
- Session duration (Number)
- Product tier/plan (Single-line text)
Tip
Group related usage properties together using property groups to keep your data organized and easily accessible.
2
Set Up Data Source Connection
Go to Settings > Integrations > Connected Apps. If your product has a direct HubSpot integration, click Browse App Marketplace and search for your platform. For custom integrations, navigate to Settings > Integrations > API key to generate an API key, or use Private Apps to create OAuth tokens for secure data transfer.
Tip
Private Apps offer better security and more granular permissions compared to API keys for production integrations.
3
Configure Data Mapping
In your chosen integration method, map your product usage fields to the HubSpot properties you created. Ensure data types match between systems:
- User ID → HubSpot Contact ID or Email
- Usage timestamps → Date properties
- Numeric metrics → Number properties
- Categorical data → Single-line text or dropdown properties
Tip
Use email addresses as the primary identifier when possible, as HubSpot can automatically match and deduplicate contacts based on email.
4
Set Up Automated Data Sync
Configure your data pipeline to sync usage data regularly. For API-based integrations, set up scheduled jobs using tools like
cron or cloud functions. For third-party tools like Zapier or PieSync, create triggers based on:- Time intervals (daily/hourly sync)
- Specific user actions
- Data threshold changes
Tip
Start with less frequent syncing (daily) and increase frequency based on your team's needs to avoid hitting API rate limits.
5
Create Usage-Based Contact Lists
Navigate to Contacts > Lists and click Create list. Select Active list for dynamic segmentation. Set up filters using your usage properties:
- Active users: Last login date is within 30 days
- Power users: Feature usage count is greater than 100
- At-risk users: Last login date is more than 60 days ago
Tip
Use active lists so your segments automatically update as new usage data flows in from your product.
6
Build Usage-Triggered Workflows
Go to Automation > Workflows and create new workflows triggered by usage data changes. Set enrollment triggers such as:
- Property value changes (usage count increases)
- List membership (joins 'at-risk users' list)
- Form submission combined with usage data
Tip
Include re-enrollment settings for workflows that should trigger multiple times as usage patterns change over time.
7
Create Usage Analytics Dashboard
Navigate to Reports > Dashboards and create a new dashboard for product usage insights. Add reports such as:
- Contact-based reports showing usage trends
- Custom reports filtering by usage properties
- Attribution reports connecting usage to deals
Tip
Share the dashboard with your customer success and product teams to align on user engagement metrics and identify expansion opportunities.
Troubleshooting
Data not syncing or appearing in HubSpot
Check API rate limits and authentication credentials. Verify that contact matching is working correctly by testing with known email addresses. Review error logs in your integration tool and ensure proper field mapping between systems.
Duplicate contacts created during usage data import
Ensure you're using email addresses or HubSpot Contact IDs for matching. Navigate to Settings > Properties > Contact Information and verify that email is set as a unique identifier. Use HubSpot's deduplication tools if duplicates already exist.
Usage data appearing in wrong format or properties
Review your field mapping configuration and ensure data types match between your product and HubSpot properties. Check for timezone differences in date fields and format numeric data consistently before sending to HubSpot.
Workflows not triggering based on usage data updates
Verify that workflow enrollment triggers are set correctly and that re-enrollment is enabled if needed. Check that the contact meets all enrollment criteria and isn't already enrolled. Review workflow history for specific contacts to identify enrollment issues.
Ready to get started with HubSpot?
Put this tutorial into practice. Visit HubSpot and follow the steps above.
Visit HubSpot →