QuickBooks Sales Tax API (Java/Spring Boot)

This Spring Boot app authenticates with QuickBooks via OAuth 2.0 (Java SDK), fetches Customers/Items via the Accounting API, and calculates Sales Tax using the Sales Tax GraphQL API.

Features

• Complete Sales Tax Operations (UI demo)
  • ✅ Calculate: real-time tax calculations for transactions (GraphQL)
  • ✅ Customer/Item retrieval via Accounting API
  • ✅ Input builder: select customer/item, shipping ZIPs, units, and unit value
• GraphQL Integration
  • Uses indirectTaxCalculateSaleTransactionTax mutation
  • Variables prepared dynamically from form input
• OAuth 2.0 (Java SDK)
  • Discovery-based environment handling
  • Secure redirect with configurable URI
• Diagnostics: GET /debug/config returns non-sensitive runtime config

Prerequisites

• Java 17 or higher
• Gradle 7.0 or higher
• QuickBooks Developer account and a QuickBooks Online company
• ngrok (for local development)

Endpoints

• / — Home page
• /connect — Initiate OAuth flow
• /callback — OAuth callback
• /calculate_tax — Run Sales Tax GraphQL calculation
• /debug/config — Non-sensitive runtime config

Dependencies

Runtime

• Spring Boot Web (spring-boot-starter-web)
• Spring Boot Thymeleaf (spring-boot-starter-thymeleaf)
• Intuit QuickBooks SDKs:
  • ipp-v3-java-devkit (6.7.0)
  • oauth2-platform-api (6.7.0)
  • ipp-v3-java-data (6.7.0)
• Jackson Databind (JSON)
• Spring Session Core (for session management)

Testing

• Spring Boot Starter Test (JUnit 5/Jupiter, AssertJ, Mockito)
• Spring Test (MockMvc, MockRestServiceServer)

Project Structure

SampleApp-SalesTax-Java/
├── src/main/java/com/quickbooks/demo/
│ ├── Application.java
│ ├── config/
│ ├── controller/
│ └── service/
├── src/main/resources/
│ ├── application.yml
│ ├── graphql/
│ │ ├── sales_tax.graphql
│ │ └── graphql_variables.json
│ ├── static/
│ └── templates/
└── README.md

Required OAuth Scopes

• com.intuit.quickbooks.accounting — access accounting data (customers, items)
• indirect-tax.tax-calculation.quickbooks — Sales Tax GraphQL access

Sales tax calculation behavior (nexus)

• QuickBooks Automated Sales Tax (AST) is nexus-driven. Tax is charged only when your company has nexus (registration) in the ship-to state.
• The API accepts any US ZIP, but without nexus for that destination you will typically get $0 tax (and in some environments you may see an error).
• For non-zero tax: enable Sales Tax in QBO, add nexus for destination states, use a taxable item, and provide a valid US ship-to address/ZIP in a nexus state.

Automated Sales Tax (AST) setup (production companies)

AST is US-only and supported in production. To get non-zero tax values:

1. Enable Sales Tax in QBO

• Taxes → Sales tax → Set up sales tax

2. Add nexus (registration) for destination states

• Taxes → Sales tax → Sales tax settings → Add state
• Pick the state, set effective date, filing frequency, agency

3. Create a taxable item

• Sales → Products and services → New → mark “Is taxable”

4. Ensure a customer exists with a US address

5. Re-authenticate if necessary (scopes already include indirect-tax.tax-calculation.quickbooks)

Testing note: The ship-to ZIP must be in a state where you have nexus. Example: if you added nexus for CA, test with 94043 (Mountain View, CA); for UT, test with 84041 (Layton, UT).

Setup

1. Clone the repository

git clone <repository-url>cd SampleApp-SalesTax-Java

2. Start ngrok

ngrok http 8080

3. Configure your QuickBooks app

• Visit the Intuit Developer Portal (https://developer.intuit.com/app/developer/myapps)
• Create an app (or use an existing one)
• Enable the scopes above
• Add your redirect URI (e.g., https://your-ngrok-url.ngrok-free.app/callback)

4. Configure application settings

Option A: Use environment variables

export QB_CLIENT_ID=your_client_id
export QB_CLIENT_SECRET=your_client_secret
export QB_REDIRECT_URI=https://your-ngrok-url.ngrok-free.app/callback
export QB_ENVIRONMENT=production # or sandboxexport QB_GRAPHQL_URL=https://qb.api.intuit.com/graphql
export QB_BASE_URL=https://quickbooks.api.intuit.com
export QB_MINOR_VERSION=75
export QB_SCOPES="com.intuit.quickbooks.accounting,indirect-tax.tax-calculation.quickbooks"

Option B: Use application.yml (create at src/main/resources/application.yml)

server:
port: 8080spring:
application:
name: quickbooks-sdk-demothymeleaf:
cache: falsequickbooks:
# INSTRUCTIONS: Copy this block into application.yml and replace with your credentialsclient-id: ${QB_CLIENT_ID:your_quickbooks_client_id_here}client-secret: ${QB_CLIENT_SECRET:your_quickbooks_client_secret_here}environment: ${QB_ENVIRONMENT:production} # Use 'sandbox' for development, 'production' for liveredirect-uri: ${QB_REDIRECT_URI:https://your-ngrok-url.ngrok-free.app/callback}base-url: ${QB_BASE_URL:https://quickbooks.api.intuit.com} # If using sandbox, set to https://sandbox-quickbooks.api.intuit.comgraphql-url: ${QB_GRAPHQL_URL:https://qb.api.intuit.com/graphql}minor-version: ${QB_MINOR_VERSION:75}deep-link-template: ${QB_DEEP_LINK_TEMPLATE:https://app.qbo.intuit.com/app/invoice?txnId=%s} # sandbox: https://app.sandbox.qbo.intuit.com/app/invoice?txnId=%sscopes:
- com.intuit.quickbooks.accounting
- project-management.projectlogging:
level:
com.quickbooks.demo: DEBUGorg.springframework.graphql: DEBUG

Tip: Use the config template safely

• Copy the template to your local config file:
  • macOS/Linux: cp src/main/resources/application.yml.template src/main/resources/application.yml
  • Windows (PowerShell): Copy-Item src/main\resources\application.yml.template src/main\resources\application.yml
• Edit application.yml with your real credentials and URLs.
• src/main/resources/application.yml is in .gitignore, so your secrets won’t be committed. Keep the .template file in git as a reference only.

5. Run the application

./gradlew bootRun

Usage

1. Visit http://localhost:8080
2. Click "Connect to QuickBooks" to authenticate (redirects to /connect)
3. After auth, the home page loads Customers and Items from your QBO company
4. Enter ship-from/to ZIPs, number of units, and unit value (or extend to full free-form addresses)
5. Click "Calculate Tax" to execute the Sales Tax GraphQL mutation and view the result
6. Optional: visit /debug/config to verify environment, endpoints, and scopes

Screenshots (expected flow)

Common Issues

1. Insufficient scope (403)

• Ensure both scopes are configured and granted during auth
• If you change scopes, re-authenticate to obtain a new token

2. Invalid client or redirect URI

• Verify Client ID/Secret
• Ensure redirect-uri exactly matches the Developer Portal configuration

3. Invalid redirect_uri query parameter

• The QuickBooks OAuth page shows: "The redirect_uri query parameter value is invalid".
• Fix by making the values match EXACTLY (scheme, host, path) between:
  • Your Intuit Developer Portal app: Keys & OAuth → Redirect URIs
  • Your app config: src/main/resources/application.yml → quickbooks.redirect-uri
• Tips:
  • Use HTTPS (required for production); ngrok URL must match the registered value.
  • Include the path (typically /callback). No trailing slashes unless registered that way.
  • After changing the redirect URI in either place, restart the app and redo the OAuth flow.

3. Environment mismatch

• Ensure environment matches the company you connect to (sandbox vs production)
• Also update the URLs to match the environment:
  • production: base-url=https://quickbooks.api.intuit.com, graphql-url=https://qb.api.intuit.com/graphql
  • sandbox: base-url=https://sandbox-quickbooks.api.intuit.com, graphql-url=https://qb-sandbox.api.intuit.com/graphql

4. GraphQL limitations (e.g., error -37109)

• Ensure Sales Tax is enabled for the connected company
• Use valid QuickBooks customer IDs and product/variant IDs
• Provide full free-form addresses if ZIP-only returns errors

5. First-time "double connect" (only on initial login)

• Cause: If you load the UI on one host (e.g., http://localhost:8080) but your OAuth redirect-uri is on another (e.g., https://<ngrok>.ngrok-free.app/callback), the OAuth callback writes tokens to a different session (ngrok domain), while your visible page is on localhost. The page won’t see the token until you reconnect on the same host.
• Symptoms: First connect appears successful in logs, but the home page still shows "Connect to QuickBooks". A second click works, and future connects are fine.
• Fixes:
  • Open the app using the same host as your redirect-uri (visit https://<ngrok>.ngrok-free.app/ instead of http://localhost:8080).
  • Or change quickbooks.redirect-uri to match the host you actually use, and update the same value in the Intuit Developer Portal.
• Optional hardening (behind proxies):
  • In application.yml, consider:

server:
forward-headers-strategy: nativeservlet:
session:
cookie:
same-site: Laxsecure: true

• Store a random OAuth state in the session on /connect and validate it in /callback.
• Remove prompt=consent in QuickBooksOAuthService#getAuthorizationUrl if you don’t need forced re-consent.

License

This project is licensed under the Apache License 2.0 — see LICENSE.

Support

For support, visit the Intuit Developer Community (https://help.developer.intuit.com/s/) or open an issue in this repository.