HubSpot Commerce MCP Server

Create a powerful Model Context Protocol (MCP) server for HubSpot Commerce in minutes with our AI Gateway. This guide walks you through setting up seamless commerce integration with enterprise-grade security and instant OAuth authentication.

About HubSpot Commerce API

HubSpot Commerce Hub enables businesses to collect payments, manage subscriptions, and report on revenue directly within HubSpot. The Commerce API provides comprehensive access to:

• Payment Processing: Quotes, invoices, and payment collection
• Product Catalog: Products, pricing, and line items
• Subscription Management: Recurring billing and subscriptions
• Commerce Bridge: Sync with external commerce systems
• Revenue Reporting: Payment analytics and forecasting
• Tax Management: Automated tax calculations
• Multi-Currency: Global payment support
• Checkout Experience: Embedded payment links

Key Features

• REST API v3: Modern API with enhanced capabilities
• Unified Platform: Integrated with CRM and Marketing
• Payment Links: No-code payment collection
• Subscription Billing: Automated recurring payments
• Revenue Analytics: Built-in reporting tools
• PCI Compliance: Secure payment processing
• Multi-Currency: 135+ supported currencies
• Tax Automation: Integrated tax calculations

What You Can Do with HubSpot Commerce MCP Server

The MCP server transforms HubSpot Commerce API into a natural language interface, enabling AI agents to:

Payment Management

• Payment Operations

  • "Create payment link for consulting services"
  • "Process invoice payment for customer"
  • "Set up recurring subscription billing"
  • "Issue refund for order #12345"

• Payment Tracking

  • "Show all pending payments this month"
  • "Find overdue invoices needing follow-up"
  • "Track payment success rates"
  • "Monitor failed payment attempts"

• Payment Methods

  • "Add new payment method for customer"
  • "Update credit card on file"
  • "Set default payment method"
  • "Manage ACH bank transfers"

Product Catalog

• Product Management

  • "Create new product with pricing tiers"
  • "Update product pricing for all SKUs"
  • "Set up volume discount rules"
  • "Manage product variants and options"

• Pricing Configuration

  • "Create tiered pricing structure"
  • "Set up promotional pricing"
  • "Configure currency-specific prices"
  • "Manage tax-inclusive pricing"

• Line Items

  • "Add custom line items to quotes"
  • "Apply discounts to specific items"
  • "Bundle products together"
  • "Track inventory levels"

Quotes & Invoices

• Quote Management

  • "Generate quote for enterprise deal"
  • "Add terms and conditions to quote"
  • "Set quote expiration date"
  • "Convert quote to invoice"

• Invoice Operations

  • "Create invoice from closed deal"
  • "Send invoice with payment link"
  • "Apply partial payments to invoice"
  • "Track invoice payment status"

• Document Customization

  • "Customize quote template design"
  • "Add company branding to invoices"
  • "Include custom fields in documents"
  • "Set up approval workflows"

Subscription Management

• Subscription Creation

  • "Set up monthly subscription plan"
  • "Create annual billing cycle"
  • "Configure trial periods"
  • "Manage subscription upgrades"

• Billing Management

  • "Update subscription pricing"
  • "Change billing frequency"
  • "Pause subscription temporarily"
  • "Cancel and refund subscription"

• Renewal Automation

  • "Configure auto-renewal settings"
  • "Send renewal reminders"
  • "Handle failed renewals"
  • "Track churn metrics"

Revenue Analytics

• Financial Reporting

  • "Show monthly recurring revenue"
  • "Track revenue by product line"
  • "Analyze payment method trends"
  • "Forecast revenue projections"

• Performance Metrics

  • "Calculate average order value"
  • "Monitor conversion rates"
  • "Track payment success rates"
  • "Analyze subscription metrics"

• Customer Analytics

  • "Show lifetime value by segment"
  • "Track purchase frequency"
  • "Identify upsell opportunities"
  • "Monitor payment behavior"

Multi-Currency & Tax

• Currency Management

  • "Set up multi-currency pricing"
  • "Configure exchange rates"
  • "Display prices in local currency"
  • "Handle currency conversions"

• Tax Configuration

  • "Set up tax rates by region"
  • "Configure tax-exempt customers"
  • "Generate tax reports"
  • "Manage VAT settings"

• Compliance

  • "Ensure PCI compliance"
  • "Manage data privacy settings"
  • "Configure regional requirements"
  • "Track audit trails"

Prerequisites

• Access to Cequence AI Gateway
• HubSpot account with Commerce Hub
• Super Admin or Commerce permissions
• App creation capabilities in HubSpot

Step 1: Create HubSpot App

Before setting up the MCP server, you need to create an app in HubSpot.

1.1 Access HubSpot Developers

1. Navigate to developers.hubspot.com
2. Sign in with your HubSpot account
3. Click Manage apps

1.2 Create New App

1. Click Create app
2. Fill in app details:
   • App name: "AI Gateway Commerce MCP"
   • Description: "MCP server for Commerce Hub integration"

1.3 Configure OAuth

1. Navigate to Auth tab
2. Set Redirect URL:

   https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback

3. Select required scopes (see Available Scopes section)

1.4 Get Credentials

1. Go to App info tab
2. Copy App ID
3. Copy Client ID
4. Copy Client secret

Step 2: Access AI Gateway Apps

1. Log in to your Cequence AI Gateway dashboard
2. Navigate to Apps in the left sidebar
3. You'll see the list of available third-party applications

Step 3: Find and Select HubSpot Commerce API

1. In the Apps section, browse through the Third-party category
2. Look for HubSpot Commerce or use the search function
3. Click on the HubSpot Commerce API card to view details

Step 4: Create MCP Server

1. Click the Create MCP Server button on the API card
2. You'll be redirected to the MCP Server creation wizard

Step 5: Configure API Endpoints

In the App Configuration step:

1. Base URL is pre-filled: https://api.hubapi.com
2. Select API endpoints to expose to your MCP server
3. Click Next to proceed

Step 6: MCP Server Basic Setup

Configure your MCP server details:

1. MCP Server Name: Enter a descriptive name

   • Example: "HubSpot Commerce Hub"

2. Description (Optional): Add details

   • Example: "Payment processing and subscription management"

3. Production Mode: Toggle based on your needs

4. Click Next to continue

Step 7: Configure Authentication

Fill in OAuth configuration:

1. Authentication Type: Select OAuth 2.0

2. OAuth settings:

   • Authorization URL:

     https://app.hubspot.com/oauth/authorize

   • Token URL:

     https://api.hubapi.com/oauth/v1/token

   • Client ID: From HubSpot app
   • Client Secret: From HubSpot app
   • Redirect URI: Your callback URL

3. Scopes: Select required scopes

Available HubSpot Commerce OAuth Scopes

Commerce Operations

• e-commerce
  • Full commerce functionality
  • Payment processing
  • Product management
  • Order handling

Line Items & Products

• line_items
  • Manage line items
  • Product catalog access
  • Pricing operations
  • Discount management

Quotes & Invoices

• quotes
  • Create and manage quotes
  • Quote templates
  • Approval workflows
  • Quote analytics

Related Scopes

• contacts

  • Customer management
  • Payment methods
  • Purchase history
  • Contact properties

• deals

  • Deal-based commerce
  • Revenue tracking
  • Pipeline management
  • Deal properties

Recommended Scope Combinations

For Payment Processing:

e-commerce
line_items
contacts

For Full Commerce:

e-commerce
line_items
quotes
contacts
deals

Step 8: Configure Security

1. API Protection: Toggle ON to enable
2. Click Next to continue

Step 9: Choose Deployment Method

Select deployment preference and click Next.

Step 10: Review and Deploy

Review configuration and click Create & Deploy.

Using Your HubSpot Commerce MCP Server

With Claude Desktop

{
  "servers": {
    "hubspot-commerce": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-client-id"
      }
    }
  }
}

Natural Language Commands

• "Create payment link for $500 consulting fee"
• "Show all subscriptions renewing this month"
• "Generate invoice for closed deal"
• "Update product pricing to $99/month"
• "Track failed payments from last week"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'access-token'
  }
});

// Create product
const product = await mcpClient.hubspot.products.create({
  name: 'Premium Subscription',
  price: 9900, // in cents
  recurring_billing_frequency: 'monthly',
  description: 'Full access to all features'
});

// Create payment link
const paymentLink = await mcpClient.hubspot.paymentLinks.create({
  amount: 50000, // $500.00
  currency: 'USD',
  name: 'Consulting Services',
  redirectUrl: 'https://example.com/thank-you'
});

// Create subscription
const subscription = await mcpClient.hubspot.subscriptions.create({
  lineItems: [{
    priceId: 'price-id',
    quantity: 1
  }],
  associatedObjectId: 'contact-id',
  associatedObjectType: 'CONTACT'
});

// Get revenue analytics
const revenue = await mcpClient.hubspot.analytics.getRevenue({
  frequency: 'monthly',
  dateRange: 'last_quarter'
});

Common Use Cases

Payment Processing

• One-time payment collection
• Recurring subscriptions
• Invoice management
• Payment method updates
• Refund processing

Revenue Operations

• Quote-to-cash workflows
• Revenue recognition
• Subscription analytics
• Churn prevention
• Upsell tracking

Financial Integration

• ERP synchronization
• Accounting exports
• Tax compliance
• Multi-currency handling
• Financial reporting

Security Best Practices

1. OAuth Security:

   • Secure token storage
   • Regular token refresh
   • Scope minimization
   • Access monitoring

2. Payment Security:

   • PCI compliance
   • Encrypted transmission
   • Secure webhooks
   • Fraud detection

3. Data Protection:

   • Customer data privacy
   • Payment data handling
   • Audit logging
   • Access controls

Troubleshooting

Common Issues

1. 401 Unauthorized

   • Check OAuth token
   • Verify scopes
   • Refresh expired token
   • Validate credentials

2. Payment Failures

   • Check payment method
   • Verify amount limits
   • Review error codes
   • Contact support

3. Sync Issues

   • Check API limits
   • Verify data mapping
   • Review sync logs
   • Validate webhooks

Getting Help

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• HubSpot Docs: developers.hubspot.com

---