Skip to main content

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 manage orders, process payments, and handle subscriptions directly within HubSpot. The Commerce API provides comprehensive access to:

  • Order Management: Create, update, and track customer orders
  • Shopping Cart Operations: Manage cart functionality and checkout
  • Payment Processing: Handle payments, refunds, and payment methods
  • Invoice Management: Generate, send, and track invoices
  • Subscription Billing: Manage recurring payments and subscriptions

Key Features​

  • REST API v3: Modern API with full CRUD capabilities
  • Unified Platform: Integrated with CRM and Marketing
  • Order Management: Complete order lifecycle management
  • Payment Processing: Secure payment handling
  • Invoice Generation: Automated invoice creation and tracking
  • Subscription Management: Recurring billing automation
  • Cart Operations: Shopping cart functionality
  • Real-time Updates: Live data synchronization

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:

Order Management​

  • Smart Order Operations

    • "Create a new order for customer John Smith with $500 consulting fee"
    • "Update order #12345 to change currency from USD to EUR"
    • "Show all orders created this month with total value over $1000"
    • "Cancel all pending orders older than 30 days"

  • Order Tracking

    • "Find orders with payment status 'pending'"
    • "Show order history for customer ID 45678"
    • "Track order fulfillment status"
    • "Generate order summary report for Q1"

  • Order Analytics

    • "Calculate average order value for the past quarter"
    • "Show top customers by order volume"
    • "Track order conversion rates"
    • "Analyze order trends by product category"

Shopping Cart Management​

  • Cart Operations

    • "Create a new shopping cart for customer"
    • "Add products to cart with specific quantities"
    • "Update cart currency to match customer location"
    • "Clear abandoned carts older than 7 days"

  • Cart Analytics

    • "Show cart abandonment rates by product category"
    • "Track average cart value trends"
    • "Find carts with high-value items"
    • "Analyze cart conversion rates"

  • Cart Automation

    • "Auto-apply discount codes for returning customers"
    • "Set up cart recovery workflows"
    • "Configure cart expiration rules"
    • "Manage cart-to-order conversion"

Payment Processing​

  • Payment Operations

    • "Process payment for order #12345 with amount $299.99"
    • "Create payment record for subscription renewal"
    • "Update payment status to 'completed'"
    • "Track payment processing times"

  • Payment Analytics

    • "Show all failed payments from last week"
    • "Calculate payment success rates by method"
    • "Track payment volume trends"
    • "Analyze payment method preferences"

  • Payment Automation

    • "Set up automatic payment retry for failed transactions"
    • "Configure payment notifications"
    • "Manage payment method updates"
    • "Handle payment disputes and refunds"

Invoice Management​

  • Invoice Operations

    • "Create invoice for customer with $1,200 consulting fee"
    • "Send invoice #INV-001 to customer email"
    • "Update invoice currency from USD to EUR"
    • "Mark invoice as paid when payment received"

  • Invoice Tracking

    • "Find all overdue invoices from last month"
    • "Show invoice payment status for customer"
    • "Track invoice generation trends"
    • "Generate invoice aging report"

  • Invoice Automation

    • "Auto-generate invoices for completed orders"
    • "Set up invoice payment reminders"
    • "Configure invoice templates"
    • "Manage invoice approval workflows"

Subscription Management​

  • Subscription Operations

    • "Create monthly subscription for $99/month plan"
    • "Update subscription name to 'Premium Plan'"
    • "Show all active subscriptions this quarter"
    • "Cancel subscription for customer ID 12345"

  • Subscription Analytics

    • "Track subscription renewal rates"
    • "Calculate monthly recurring revenue"
    • "Show subscription churn analysis"
    • "Monitor subscription upgrade patterns"

  • Subscription Automation

    • "Set up automatic subscription renewals"
    • "Configure subscription billing cycles"
    • "Manage subscription lifecycle events"
    • "Handle subscription payment failures"

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. Go to Development -> Legacy Apps
  4. Click Create

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​

Configure the appropriate scopes based on your application needs:

Core Commerce Operations​

  • e-commerce
    • Full commerce functionality
    • Payment processing
    • Order management
    • Cart operations

Order Management​

  • crm.objects.orders.read

    • Read order information
    • View order details
    • Track order status
    • Access order history

  • crm.objects.orders.write

    • Create new orders
    • Update order details
    • Manage order properties
    • Delete orders

Cart Operations​

  • crm.objects.carts.read

    • Read cart information
    • View cart contents
    • Track cart status
    • Access cart history

  • crm.objects.carts.write

    • Create shopping carts
    • Update cart contents
    • Manage cart properties
    • Delete carts

Payment Processing​

  • crm.objects.commercepayments.read

    • Read payment information
    • View payment details
    • Track payment status
    • Access payment history

  • crm.objects.commercepayments.write

    • Create payment records
    • Update payment details
    • Manage payment properties
    • Process payments

Invoice Management​

  • crm.objects.invoices.read

    • Read invoice information
    • View invoice details
    • Track invoice status
    • Access invoice history

  • crm.objects.invoices.write

    • Create invoices
    • Update invoice details
    • Manage invoice properties
    • Send invoices

Subscription Management​

  • crm.objects.subscriptions.read

    • Read subscription information
    • View subscription details
    • Track subscription status
    • Access subscription history

  • crm.objects.subscriptions.write

    • Create subscriptions
    • Update subscription details
    • Manage subscription properties
    • Cancel subscriptions

For Comprehensive Commerce (Recommended):

e-commerce
crm.objects.orders.read
crm.objects.orders.write
crm.objects.carts.read
crm.objects.carts.write
crm.objects.commercepayments.read
crm.objects.commercepayments.write
crm.objects.invoices.read
crm.objects.invoices.write
crm.objects.subscriptions.read
crm.objects.subscriptions.write

For Basic Operations:

e-commerce
crm.objects.orders.read
crm.objects.orders.write
crm.objects.carts.read
crm.objects.carts.write

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​

  1. Open Claude Desktop settings
  2. Add your MCP server: 
    {
      "mcpServers": {
        "HubSpot Commerce": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ]
        }
      }
    }

With Cursor IDE​

  1. Open Cursor IDE and go to Settings (Cmd/Ctrl + ,).
  2. Navigate to Tools & Integrations and click New MCP Server.
  3. Add your MCP server: 
    {
      "mcpServers": {
        "HubSpot Commerce": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ]
        }
      }
    }

With Windsurf IDE​

  1. Open Windsurf IDE and click Windsurf - Settings (bottom right) or press Cmd/Ctrl + Shift + P.
  2. Type Open Windsurf Settings and select Advanced → Cascade.
  3. Click Add Server → Add custom server +.
  4. Add your MCP server: 
    {
      "mcpServers": {
        "HubSpot Commerce": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ],
          "disabled": false,
          "alwaysAllow": []
        }
      }
    }

Natural Language Commands​

  • "Create a new order for customer John Smith with $500 consulting fee"
  • "Show all subscriptions renewing this month"
  • "Generate invoice for customer with $1,200 amount"
  • "Update order currency from USD to EUR"
  • "Track failed payments from last week"

Common Use Cases​

Order Management​

  • Automated order creation
  • Order status tracking
  • Order fulfillment workflows
  • Order analytics and reporting

Payment Processing​

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

Revenue Operations​

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

Financial Integration​

  • ERP synchronization
  • Accounting exports
  • Invoice management
  • 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​