​
HubSpot Integration Development

This guide covers developing and testing the HubSpot integration for Billy.

​
Overview

HubSpot integration allows Billy to:
  • Create and manage contacts
  • Create invoices and estimates
  • Associate invoices with deals
  • Manage billing plans and subscriptions
  • Handle customer relationships

​
Development Setup

​
1. Access HubSpot Developer Account

Go to our HubSpot Developer Account to create and manage your development application.

​
2. Create Your Development Application

  1. Create New Application
    • Click “Create app”
    • Choose “Private app” type
    • Name: “Billy - [Your Name] [Dev]”
  2. Configure OAuth Settings
    • Redirect URI: https://localhost:3000/oauth/hubspot/redirect_uri
    • Scopes: Configure based on your needs
  3. Get Credentials
    • Copy your Client ID and Client Secret
    • Note your API Key

​
3. Environment Configuration

Add these variables to your .env.local: 
# HubSpot [Dev]
HUBSPOT_REDIRECT_URI=https://localhost:3000/oauth/hubspot/redirect_uri
HUBSPOT_PENNYLANE_API_KEY=YOUR_API_KEY
HUBSPOT_PENNYLANE_CLIENT_SECRET=YOUR_CLIENT_SECRET
HUBSPOT_PENNYLANE_CLIENT_ID=YOUR_CLIENT_ID

​
4. Enable Application

  1. Login to HubSpot with your development account
  2. Navigate to your app in the developer portal
  3. Enable the application on your HubSpot account

​
CRM Cards Development

​
Setting Up CRM Cards

  1. Go to CRM Cards in your HubSpot app
  2. Select the card you want to configure
  3. Paste the URL in the corresponding field
  4. Check target types that apply to your card
  5. Save configuration

​
Available CRM Cards

  • Invoice Creation: Create invoices from deals
  • Estimate Management: Handle quotes and estimates
  • Customer Association: Link invoices to contacts
  • Billing Plans: Manage subscription billing

​
Testing Your Integration

​
Local Testing

  1. Start your development server 
    pnpm dev
  2. Test OAuth flow
    • Navigate to HubSpot integration setup
    • Complete the OAuth authorization
    • Verify redirect works correctly
  3. Test API calls
    • Create test contacts
    • Generate test invoices
    • Verify data synchronization

​
Preview Environment Setup

For testing in preview environments:
  1. Add environment variables to your Vercel preview branch:
    • HUBSPOT_PENNYLANE_CLIENT_SECRET
    • HUBSPOT_PENNYLANE_CLIENT_ID
  2. Unprotect domain on Vercel:
  3. Update redirect URIs to use your preview domain

​
Getting Help