QuickBooks Sales Tax API

A Node Js App for calculating sales tax using QuickBooks Online Sales Tax API via GraphQL and the Intuit SDK.

Features

Complete Sales Tax Operations: Full tax calculation and lookup capabilities
- ✅ Calculate: Real-time tax calculations for transactions
- ✅ Customer Integration: Automatic QuickBooks customer lookup and resolution
GraphQL Integration: Uses QuickBooks Sales Tax GraphQL API for efficient tax operations
- Tax Calculation Mutation: indirectTaxCalculateSaleTransactionTax for real-time calculations
- Dynamic Variables: Automatic conversion of REST requests to GraphQL variables
- Schema Compliance: Exact implementation of QuickBooks Sales Tax mutation structure
Dynamic Input Processing: No hardcoded values - all data comes from request input
- Customer ID: Uses provided customerId or auto-fetches first available QuickBooks customer
- Addresses: Requires shipFromAddress or businessAddress input for shipping calculations
- Item IDs: Accepts QuickBooks-compatible numeric itemId values or defaults to "1"
Intuit Node JS SDK: Built with official Intuit Node JS SDK for QuickBooks API v3 with OAuth 2.0

OAuth Implementation

This API implements OAuth 2.0 as per Intuit Node JS specifications:

Required OAuth Scopes

The API requires the following OAuth scopes for full functionality:

com.intuit.quickbooks.accounting - Access to QuickBooks accounting data and customer information
indirect-tax.tax-calculation.quickbooks - Required for Sales Tax API access
openid, profile, email, phone, address - User identity information

Note: The indirect-tax.tax-calculation.quickbooks scope is essential for accessing QuickBooks Sales Tax GraphQL API endpoints.

Endpoints

Production: https://qb.api.intuit.com/graphql
Sandbox: https://qb-sandbox.api.intuit.com/graphql

Prerequisites

Node.js: Version 12.0.0 or higher (recommended: 14.x or 16.x)
npm: Comes with Node.js installation

Check Node.js Version

node --version
npm --version

Getting Started

Install Dependencies
```
npm install
```
Configure QuickBooks App
- Create a QuickBooks app at https://developer.intuit.com
- Update .env with your app credentials
Run the Application
```
node index.js
```
Complete OAuth Authentication
- Navigate to http://localhost:3000
- Click on the 'Connect to Quickbooks' Button
- Complete the QuickBooks OAuth flow
- It Navigates you back to the Home Page where you can now have access to the Sales Tax UI.
Test the API
- Navigate to http://localhost:3000 for the web interface
- Use the UI to perform the various operations.

Configuration

Create a .env file with your QuickBooks app credentials:

PORT=3000

CLIENT_ID: PUT_YOUR_CLIENT_ID_HERE
CLIENT_SECRET: PUT_YOUR_CLIENT_SECRET_HERE
ENVIRONMENT: PUT_THE_ENVIRONMENT_HERE
REDIRECT_URI: http://localhost:3000/api/auth/

Authentication

This API requires OAuth 2.0 authentication with QuickBooks Online. The authentication flow includes:

OAuth Authorization: Visit /api/auth/login to start the flow
Scope Configuration: Configurable scopes
Sales Tax Permissions: Requires indirect-tax.tax-calculation.quickbooks scope for Sales Tax API access

Example OAuth Flow

# 1. Initiate OAuth
curl "http://localhost:3000/api/auth/login"

# 2. Complete authorization in browser, then test API

API Endpoints

OAuth Management

GET /api/auth/login - Initiate OAuth authorization with QuickBooks
GET /api/auth/callback - Handle OAuth callback from QuickBooks
GET /api/auth/retrieveToken - Retrieve Token

Sales Tax Operations

POST /api/quickbook/salestax/indirect-tax - Calculate tax for a transaction (uses indirectTaxCalculateSaleTransactionTax mutation)
GET /api/quickbook/salestax/customers - Get QuickBooks customers for testing and integration

GraphQL Implementation

This API implements the exact QuickBooks Sales Tax GraphQL schema:

Mutation Used

mutation IndirectTaxCalculateSaleTransactionTax($input: IndirectTax_TaxCalculationInput!) {
  indirectTaxCalculateSaleTransactionTax(input: $input) {
    taxCalculation {
      transactionDate
      taxTotals {
        totalTaxAmountExcludingShipping {
          value
        }
      }
      subject {
        customer {
          id
        }
      }
      shipping {
        shipToAddress {
          rawAddress {
            ... on IndirectTax_FreeFormAddress {
              freeformAddressLine
            }
          }
        }
        shipFromAddress {
          rawAddress {
            ... on IndirectTax_FreeFormAddress {
              freeformAddressLine
            }
          }
        }
      }
      lineItems {
        edges {
          node {
            numberOfUnits
            pricePerUnitExcludingTaxes {
              value
            }
          }
        }
        nodes {
          productVariantTaxability {
            product {
              id
            }
          }
        }
      }
    }
  }
}

Input Variables Format

{
  "input": {
    "transactionDate": "2025-06-17",
    "subject": {
      "qbCustomerId": "1"
    },
    "shipping": {
      "shipFromAddress": {
        "freeFormAddressLine": "2600 Marine Way, Mountain View, CA 94043"
      },
      "shipToAddress": {
        "freeFormAddressLine": "2600 Marine Way, Mountain View, CA 94043"
      }
    },
    "lineItems": [
      {
        "numberOfUnits": 1,
        "pricePerUnitExcludingTaxes": {
          "value": 10.95
        },
        "productVariantTaxability": {
          "productVariantId": "1"
        }
      }
    ]
  }
}

API Input Requirements Summary

🔄 Dynamic Input Implementation

All APIs now require input data and do not rely on hardcoded values:

Main Calculate Endpoint (`POST /api/quickbook/salestax/indirect-tax`)

Required: customerAddress (complete address object)
Required: Either shipFromAddress OR businessAddress (complete address object)
Optional: customerId (auto-fetches first customer if not provided)
Optional: itemId (accepts numeric strings like "1", "2", "3", etc. - defaults to "1")
Optional: transactionDate (defaults to current date)

Customers Endpoint

No input required: Returns all available QuickBooks customers for integration

🚨 Important Validation Rules

Ship-From Address: Must provide either shipFromAddress OR businessAddress
Customer ID: If not provided, system auto-fetches first available customer
Address Completeness: All address fields (city, state, postal code) are required
Item IDs: Must be numeric strings ("1", "2", "3", etc.) - custom alphanumeric IDs will fail QuickBooks validation

API Usage Examples

1. Calculate Sales Tax for Transaction

✅ Dynamic Input Version (No Hardcoded Values):

curl -X POST "http://localhost:3000/api/quickbook/salestax/indirect-tax" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "transaction": {
      "transactionDate": "2025-06-17",
      "customerId": "1",
      "customerAddress": {
        "line1": "2600 Marine Way",
        "city": "Mountain View", 
        "state": "CA",
        "postalCode": "94043"
      },
      "shipFromAddress": {
        "line1": "123 Business St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102"
      },
      "lines": [
        {
          "amount": 10.95,
          "description": "Test Product",
          "itemId": "2"
        }
      ]
    }
  }'

Alternative with businessAddress (instead of shipFromAddress):

curl -X POST "http://localhost:3000/api/quickbook/salestax/indirect-tax" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
  "transaction": {
      "transactionDate": "2025-06-17",
      "customerAddress": {
        "line1": "2600 Marine Way",
        "city": "Mountain View", 
        "state": "CA",
        "postalCode": "94043"
      },
      "businessAddress": {
        "line1": "123 Business St",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94102"
      },
      "lines": [
        {
          "amount": 10.95,
          "description": "Test Product"
        }
      ]
    }
  }'

🔍 ItemId Validation Requirements

✅ Valid ItemId Values:

Numeric strings: "1", "2", "3", "10", etc.
No itemId provided: Defaults to "1"

❌ Invalid ItemId Values:

Custom alphanumeric: "CUSTOM-123", "PROD-456"
Generated patterns: "item_1", "product_abc"

Note: Either shipFromAddress OR businessAddress is required. If customerId is not provided, the system will automatically use the first available QuickBooks customer. ItemId must be a numeric string to pass QuickBooks validation.

GraphQL Mutation Used:

mutation IndirectTaxCalculateSaleTransactionTax($input: IndirectTax_TaxCalculationInput!) {
  indirectTaxCalculateSaleTransactionTax(input: $input) {
    taxCalculation {
      transactionDate
      taxTotals {
        totalTaxAmountExcludingShipping {
          value
        }
      }
      subject {
        customer {
          id
        }
      }
      shipping {
        shipToAddress {
          rawAddress {
            ... on IndirectTax_FreeFormAddress {
              freeformAddressLine
            }
          }
        }
        shipFromAddress {
          rawAddress {
            ... on IndirectTax_FreeFormAddress {
              freeformAddressLine
            }
          }
        }
      }
      lineItems {
        edges {
          node {
            numberOfUnits
            pricePerUnitExcludingTaxes {
              value
            }
          }
        }
        nodes {
          productVariantTaxability {
            product {
              id
            }
          }
        }
      }
    }
  }
}

Response:

{
  "success": true,
  "data": {
    "totalTaxAmount": 1.0,
    "totalAmount": 11.95,
    "lines": [
      {
        "lineNumber": 1,
        "amount": 10.95,
        "taxAmount": 1.0,
        "taxRate": 0.0913242009132420091324200913,
        "description": "Test Product",
        "taxBreakdown": [
          {
            "taxType": "Sales Tax",
            "taxName": "QuickBooks Sales Tax",
            "taxRate": 0.0913242009132420091324200913,
            "taxAmount": 1.0,
            "jurisdiction": "Mountain View, CA",
            "taxableAmount": 10.95
          }
        ]
      }
    ],
    "transactionDate": "2025-06-17T00:00:00"
  }
}

2. Get QuickBooks Customers

curl -X GET "http://localhost:5038/api/salestax/customers" \
  -H "Accept: application/json"

Response:

{
  "success": true,
  "data": [
    {
      "id": "1",
      "name": "",
      "companyName": "Amy's Bird Sanctuary",
      "active": true
    },
    {
      "id": "2",
      "name": "",
      "companyName": "Bill's Windsurf Shop",
      "active": true
    }
  ]
}

Project Structure

├── graphql/salesTax
│   ├── inirectTax.js                   # GraphQL query and variables for calculating tax
├── pages/
│   ├── index.html                      # HTML for web UI
│   └── style.css                       # Styling for the UI
├── routes/
│   ├── oauth=route.js                  # routes for authentication flow
│   ├── sales-tax-route.cs              # routes for sales tax
├── services/                       
│   ├── auth-service.js                 # service for authentication
│   └── sales-tax-service.js            # service for sales tax
├── env                                 # Configs
├── index.js                            # Application startup

GraphQL Implementation Details

This API implements the QuickBooks Sales Tax GraphQL schema with the following operations:

Tax Calculation Mutation (`indirectTaxCalculateSaleTransactionTax`)

Purpose: Calculate real-time sales tax for transactions
Method: CalculateSaleTransactionTaxAsync()
Endpoint: POST /api/quickbook/salestax/indirect-tax
GraphQL Type: Mutation with IndirectTax_TaxCalculationInput input type
Features: Dynamic customer lookup, address processing, line item support

Customer Integration (QuickBooks REST API)

Purpose: Retrieve QuickBooks customer data for tax calculations
Method: GetCustomersAsync()
Endpoint: GET /api/quickbook/salestax/customers
Integration: Uses QuickBooks REST API v3 for customer data

Dependencies

GraphQL.Client - GraphQL client for Node Js (graphql-request)
IntuitNodeSDK - Official Intuit Node JS SDK for OAuth
Express - Node Express

Implementation Details

OAuth 2.0 Flow

Authorization: Uses Intuit Node Js SDK's OAuth2Client with proper environment handling

GraphQL Integration

Real API Calls: Direct integration with QuickBooks GraphQL endpoint
Dynamic Variables: Converts REST request to GraphQL variables automatically
Customer Lookup: Automatically retrieves QuickBooks customer ID for transactions
Error Handling: Comprehensive error logging and debugging support

Security Considerations

OAuth state parameter validation
Granular permission scope
HTTPS redirect URI recommended for production

Development

The application uses:

Intuit Node JS SDK for OAuth 2.0
GraphQL.Client for API communication

Troubleshooting

Common Issues

"Cannot find module 'node:events'" Error:
- Root Cause: Using Express v5.x with Node.js < 18.0.0
- Solution: Upgrade to Node.js 18+ or use Express v4.x
- Check Version: Run node --version (should be 12.0.0+ for this project)
- Fix: Delete node_modules and package-lock.json, then run npm install
"Cannot find package 'graphql'" Error:
- Root Cause: Missing graphql peer dependency for graphql-request
- Solution: Install the missing dependency
- Fix: Run npm install graphql or npm install (package.json updated with graphql dependency)
"Invalid URI or environment" Error:
- Ensure DiscoveryDocument is set to https://appcenter.intuit.com/api/v1/connection/oauth2
- Verify Environment is set to "sandbox" or "production"
"Access Denied" GraphQL Error:
- Verify both required scopes are present in ProjectScopes
- Ensure QuickBooks company has sales tax enabled
- Check that OAuth token includes indirect-tax.tax-calculation.quickbooks scope
"-37109" Application Error:
- Configure sales tax settings in QuickBooks company
- Enable tax agencies and rates for the addresses being tested
- Verify customer exists in QuickBooks (or use hardcoded customer ID "1")
"INV-GraphQL expression=Validation failed" Error:
- Root Cause: Invalid itemId format
- Solution: Use numeric string itemIds only ("1", "2", "3", etc.)
- Avoid: Custom alphanumeric itemIds ("CUSTOM-123", "PROD-456")
- Default: If no itemId provided, system defaults to "1"

Debugging

Check application logs for detailed GraphQL request/response information
Use /api/oauth/retrieveTOken to verify token exists

Production Deployment

For production:

Update .env with production credentials
Change Environment to "production"
Update GraphQLEndpoint to "https://qb.api.intuit.com/graphql"
Update BaseUrl to "https://quickbooks.api.intuit.com"
Use HTTPS for redirect URI (required by QuickBooks)

Testing & Validation

The implementation has been comprehensively tested with real QuickBooks sandbox data:

✅ OAuth 2.0 Integration

Scope Configuration: Both required scopes (com.intuit.quickbooks.accounting + indirect-tax.tax-calculation.quickbooks) working
Authorization Flow: Complete OAuth flow using Intuit Node JS SDK

✅ GraphQL API Integration

Real API Calls: Direct integration with https://qb-sandbox.api.intuit.com/graphql
Exact Schema Implementation: IndirectTaxCalculateSaleTransactionTax mutation with proper input structure
Customer Integration: Automatic QuickBooks customer lookup and ID resolution
Dynamic Variables: Request data converted to GraphQL variables correctly

✅ All Endpoints Validated (Dynamic Input Implementation)

Endpoint	Status	Input Requirements	Test Results
`POST /api/quickbook/salestax/indirect-tax`	✅ Working	Requires `customerAddress` + (`shipFromAddress` OR `businessAddress`) + numeric `itemId`	$10.95 → $1.00 tax with itemId="1"
`GET /api/quickbook/salestax/customers`	✅ Working	No input required	Returns QuickBooks customer list for dynamic lookup

Environment Setup

Sandbox: Use qb-sandbox.api.intuit.com endpoints
Production: Use qb.api.intuit.com endpoints
Port: Default is 3000, configurable in env

License

This project is for demonstration purposes and follows QuickBooks API terms of service.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
graphql/salesTax		graphql/salesTax
pages		pages
routes		routes
services		services
.gitignore		.gitignore
README.md		README.md
env		env
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

IntuitDeveloper/SampleApp-Salestax-NodeJS

Folders and files

Latest commit

History

Repository files navigation