API Limits and Restrictions

This page documents the technical limits, rate limits, and restrictions for the QuickBooks Invoicing integration.

Overview

The integration operates within the constraints of both HubSpot’s and QuickBooks’ API rate limits, as well as our own application limits designed to ensure reliability and performance.

QuickBooks API Rate Limits

Standard Rate Limits

QuickBooks Online API enforces the following rate limits:

What this means:

• You can make up to 500 API calls per minute
• For the integration, this translates to approximately:
  • 500 invoice creations per minute (theoretical max)
  • 500 customer syncs per minute (theoretical max)
  • In practice: You’re unlikely to hit these limits with normal usage

Burst Limits

QuickBooks allows temporary bursts above the per-minute limit:

• Burst capacity: Up to 600 requests in a short burst
• Recovery time: 1 minute to restore burst capacity

Practical impact: If you create many invoices rapidly (100+ in a few seconds), you may hit the burst limit temporarily. Wait 60 seconds and try again.

Rate Limit Headers

When the integration calls QuickBooks API, responses include rate limit information:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 60

• Limit: Maximum requests per minute (500)
• Remaining: How many requests left in current window
• Reset: Seconds until rate limit resets

Integration behavior: If rate limit is approached, the integration automatically throttles requests and retries after the reset time.

HubSpot API Rate Limits

OAuth API Limits

For reading HubSpot CRM data (contacts, deals, quotes, line items):

What this means:

• The integration can read up to 100 CRM objects per 10 seconds
• Daily limit is very high - unlikely to be reached
• Multiple users can create invoices simultaneously (up to 12 concurrent)

API Usage Best Practices

The integration optimizes HubSpot API usage:

• Batch requests: When possible, fetches multiple objects in one call
• Caching: Temporarily caches deal and contact data during invoice creation (minutes)
• Lazy loading: Only fetches data when user opens CRM card or creates invoice
• No polling: Does not continuously check HubSpot for updates

Integration Application Limits

Invoice Creation Limits

Per-user limits (to prevent accidental mass creation):

Per-account limits (all users combined):

Note: These are safety limits. If you have legitimate needs exceeding these limits, contact support to discuss options.

What happens if limit is reached:

• User sees error message: “Rate limit exceeded. Please wait X minutes and try again.”
• No invoices are lost (user can retry)
• Limit automatically resets after the specified period

Customer Sync Limits

Per-user limits:

Per-account limits:

Automatic sync behavior:

• Customers are synced automatically during invoice creation
• If contact doesn’t exist in QuickBooks, integration creates it
• Sync counts toward the above limits

Settings Access Limits

Purpose: Prevents accidental or malicious rapid connection/disconnection cycles.

Data Size Limits

Invoice Field Limits

When creating invoices, the following field size limits apply:

Enforced by: QuickBooks API

What happens if exceeded:

• Truncation (description fields)
• Validation error (email, display name)
• User must reduce line item count

Customer Field Limits

Enforced by: QuickBooks API

Timeout Limits

API Request Timeouts

Retry logic:

• Exponential backoff: 1s, 2s, 4s between retries
• After 3 failures: Show error to user
• User can manually retry

Concurrency Limits

Simultaneous Invoice Creation

Per user:

• 1 invoice creation at a time per user
• Prevents duplicate invoices if user clicks “Create” multiple times

Per account:

• Up to 12 simultaneous invoice creations across all users
• Limited by HubSpot OAuth concurrent connection limit

Queue behavior:

• If 12 users are creating invoices simultaneously, 13th user sees “Please wait, trying again…”
• Automatic retry every 5 seconds
• Maximum wait time: 60 seconds

Simultaneous Settings Changes

Per account:

• 1 settings update at a time
• Prevents conflicts from multiple admins changing settings simultaneously

Lock behavior:

• If admin A is saving settings, admin B sees “Settings are being updated, please wait…”
• Automatic retry every 2 seconds
• Maximum wait time: 30 seconds

OAuth Token Limits

Token Lifespan

What this means:

• You don’t need to reconnect every hour (auto-refresh)
• As long as integration is used at least once every 100 days, tokens stay valid
• If unused for 100+ days, must reconnect

Token Refresh Limits

QuickBooks limits refresh token usage:

Integration behavior:

• Refreshes token only when needed (when access token expires)
• Caches access token for its 1-hour lifespan
• Normal usage stays well below these limits

Storage Limits

Database Storage Per Account

Impact: Negligible. No practical storage concerns.

Batch Operation Limits

Bulk Invoice Creation

The integration does NOT support bulk invoice creation (creating multiple invoices at once from a list of deals).

Current behavior:

• Must create invoices one deal at a time
• Each invoice created individually via CRM card

Future consideration:

• Bulk creation may be added in future versions
• Would still respect rate limits (throttled batch processing)

Bulk Customer Import

The integration does NOT support bulk customer import (syncing all HubSpot contacts to QuickBooks at once).

Current behavior:

• Customers synced on-demand during invoice creation
• One customer per invoice creation

Manual bulk import:

• Use QuickBooks’ native import tool to bulk import customers
• Then create invoices in HubSpot (customers will already exist)

Error Handling and Retries

Automatic Retry Behavior

User visibility:

• First retry: Silent (user doesn’t see)
• Subsequent retries: Progress indicator (“Retrying… attempt 2 of 3”)
• Final failure: Error message with details

Non-Retryable Errors

Some errors are NOT retried (user must fix them):

• Invalid credentials (incorrect Client ID/Secret)
• OAuth token revoked (must reconnect)
• Invalid data (missing required fields)
• QuickBooks validation errors (e.g., invalid tax code ID)
• Permissions errors (user lacks deal edit access)

User action required: Fix the underlying issue and retry manually.

Limits by Plan Type

The integration does NOT have different limits based on HubSpot subscription tier. All users have the same limits regardless of HubSpot plan (Free, Starter, Professional, Enterprise).

Why: The integration is priced/provided independently of HubSpot plan tiers.

Monitoring and Notifications

Rate Limit Warnings

The integration does NOT send proactive warnings when approaching limits.

User notification:

• Only when limit is actually hit
• Error message explains the limit and when it resets

Admin notification:

• No automatic notifications to admins
• Contact support if you need monitoring for your account

Usage Analytics

The integration does NOT provide usage analytics or dashboards showing:

• How many invoices created
• How close to rate limits
• API call volume

Future consideration: May be added in a future version.

Quota Increases

Requesting Higher Limits

If your business needs exceed the documented limits:

1. Contact Support:

   • Email: support@structur.app
   • Subject: “Rate Limit Increase Request”

2. Provide Details:

   • HubSpot account ID
   • Current usage patterns
   • Desired limit increase
   • Business justification

3. Review Process:

   • Support reviews request
   • May ask for additional information
   • Approval typically within 2-3 business days

4. Custom Limits:

   • Can be configured per-account
   • No additional cost for reasonable increases

Third-Party Limits

QuickBooks Company Limits

Your QuickBooks Online subscription may have limits:

Integration impact: None. The integration works within your QuickBooks subscription limits.

Note: Even with 1 user in QuickBooks, unlimited HubSpot users can create invoices via the integration (because the integration uses OAuth, not individual user accounts).

HubSpot CRM Limits

Your HubSpot subscription may have object limits:

Integration impact: Works with all HubSpot plans. No additional limits imposed.

Performance Considerations

Expected Response Times

Factors affecting speed:

• Number of line items (more = slower)
• Network latency
• QuickBooks API response time
• Whether customer already exists (new customer = slower)

Optimizing Performance

Best practices to stay within limits:

✅ Do:

• Create invoices as needed, not in bulk
• Sync customers before creating many invoices
• Use default tax codes and products (saves API calls)
• Avoid rapid clicking on “Create Invoice” button

❌ Don’t:

• Create 100+ invoices in a few minutes (will hit rate limits)
• Attempt bulk operations (not supported)
• Create duplicate invoices (check QuickBooks first)

Frequently Asked Questions

What happens if I hit a rate limit?

You’ll see an error message explaining the limit and when it resets. Wait for the specified time (typically 1 minute) and try again.

Can I increase my rate limits?

Yes, contact support with your business case. We can configure higher limits for your account.

Why do you have application limits on top of QuickBooks limits?

To ensure reliability and prevent accidental mass invoice creation (e.g., if user clicks “Create” 100 times by mistake).

Do limits apply per user or per account?

Both. There are per-user limits (to prevent individual mistakes) and per-account limits (total across all users).

What if my QuickBooks subscription has lower limits?

The integration respects QuickBooks limits. If QuickBooks rejects an invoice due to subscription limits, you’ll see the error and must upgrade your QuickBooks plan.

Are there limits on invoice amounts or line item prices?

No application limits. QuickBooks may have limits (e.g., maximum invoice amount is $9,999,999.99). See QuickBooks documentation for details.

Can I create invoices faster than the rate limits allow?

No. Rate limits are strictly enforced to comply with QuickBooks API requirements and ensure system stability.

What if I need to create 10,000 invoices in a day?

Contact support before attempting this. We can configure temporary higher limits and provide guidance on batch processing strategies.

Additional Resources

• QuickBooks API Rate Limits  - Official QuickBooks documentation
• HubSpot API Rate Limits  - Official HubSpot documentation
• Troubleshooting - Common issues and solutions
• Support - Contact us for custom limit requests