203 online 3 members  + Join RP Base  +
FreeScript

Sampleapp-Customfields-Nodejs

by IntuitDeveloper  ·  version 2026.09.15  ·  updated 2 days ago

No reviews yet

Downloads
0
Reviews
0
Size
44 KB
Code check
Clean
Licence
Apache-2.0
Released
Nov 2026

A Node.js Express API for managing QuickBooks Custom Field Definitions using the App Foundations GraphQL API and the Intuit Node.js SDK.

Sampleapp-Customfields-Nodejs
QuickBooks Custom Fields API - Node.js
A Node.js Express API for managing QuickBooks Custom Field Definitions using the App Foundations GraphQL API and the Intuit Node.js SDK.
Features
  • Complete CRUD Operations: Create, Read, Update, Delete (soft delete) for QuickBooks custom field definitions
  • App Foundations API Integration: Full implementation using QuickBooks App Foundations GraphQL API
  • Advanced Association Management: Complex entity relationships (Transactions, Contacts, Vendors, Customers)
  • Production-Ready Soft Delete: Safe deactivation-based deletion preserving data integrity
  • Schema Compliance: Complete AppFoundations_CustomFieldDefinitionInput schema support
  • Automatic Field Management: Auto-retrieval of required fields (legacyIDV2, field preservation)
  • Business Rule Enforcement: Association validation and mutual exclusivity checking
  • OAuth 2.0 with App Foundations Scopes: Secure authentication with granular permissions
  • RESTful API: Clean REST endpoints for seamless integration
  • Comprehensive Error Handling: GraphQL error parsing and detailed validation messages
  • Interactive Web Interface: Simple HTML interface for testing API operations
API Endpoints*Core Custom Field Operations (Essential)*
  • GET /api/quickbook/custom-fields - Get all custom field definitions with associations
  • POST /api/quickbook/custom-fields - Create a new custom field definition
  • PUT /api/quickbook/custom-fields/:id - Update an existing custom field definition
  • DELETE /api/quickbook/custom-fields/:id - Delete (deactivate) a custom field definition
*OAuth Authentication (Required)*
  • GET /api/auth/login - Initiate OAuth flow
  • GET /api/auth/callback - OAuth callback handler
  • POST /api/auth/retrieveToken - Get current token information
Configuration
Update your .env file with your QuickBooks app credentials:

Note: The App Foundations Custom Field Definitions API uses the production environment by default as it's not available in sandbox mode.

PORT=8080

CLIENT_ID=YOUR_CLIENT_ID
CLIENT_SECRET=YOUR_CLIENT_SECRET
ENVIRONMENT=production
REDIRECT_URI=https://your-ngrok-url.ngrok-free.app/api/auth/callback

Prerequisites
Before running this application, ensure you have the following:

Check Your Node.js Version
node --version
npm --version

Required Versions:
  • Node.js: 18.0.0 or higher
  • npm: 8.0.0 or higher
Getting Started
  1. Install Dependencies
   npm install

  1. Configure QuickBooks App
  • Create a QuickBooks app at Intuit Developer
  • Update .env with your app credentials
  • Set redirect URI to your ngrok URL: https://your-ngrok-url.ngrok-free.app/api/auth/callback

  1. Start ngrok (Required for OAuth)
   ngrok http 8080

Copy the ngrok URL and update your .env file and QuickBooks app settings.

  1. Run the Application
   npm start

  1. Access the Application
  • Open your browser to http://localhost:8080
  • Click "Connect to QuickBooks" to authenticate
  • Use the interface to manage custom fields
Custom Field Definition Features
The App Foundations API provides advanced custom field capabilities:
Data Types
  • STRING: Text values
  • NUMBER: Numeric values (decimal)
  • DATE: Date values
  • BOOLEAN: True/false values
  • DROPDOWN: Predefined options (future support)
Entity Associations
Custom fields can be associated with different QuickBooks entities and their sub-types. The API supports flexible association configurations:
*Supported Entity Types*
  • Transactions: /transactions/Transaction
  • SALE_INVOICE - Sales invoices
  • SALE_ESTIMATE - Sales estimates/quotes
  • PURCHASE_ORDER - Purchase orders
  • And more transaction types...
  • Contacts: /network/Contact
  • CUSTOMER - Customer contacts
  • VENDOR - Vendor contacts
  • EMPLOYEE - Employee contacts
*Association Configuration*
{
  "name": "Custom Field Name",
  "type": "STRING",
  "associations": [
    {
      "associatedEntity": "/transactions/Transaction",
      "active": true,
      "required": false,
      "associationCondition": "INCLUDED",
      "subAssociations": ["SALE_INVOICE", "SALE_ESTIMATE"]
    }
  ]
}

*Association Features*
  • ✅ Multiple Sub-Entities: Associate with multiple sub-types within the same entity
  • ✅ Required/Optional Fields: Control field validation per association
  • ✅ Active State Management: Enable/disable associations dynamically
  • ✅ Conditional Logic: INCLUDED or EXCLUDED association conditions
  • ❌ Mixed Entity Types: Cannot combine Contact and Transaction associations in one field
*Business Rules*
  • Single Entity Type: Each custom field can only associate with one main entity type
  • Multiple Sub-Associations: Within an entity type, you can associate with multiple sub-types
  • Mutual Exclusivity: Some sub-associations are mutually exclusive (API will return specific errors)
App Foundations GraphQL Operations
The service uses the App Foundations API with complete CRUD support:
*Queries*
  • **appFoundationsCustomFieldDefinitions**: Primary query for retrieving all custom field definitions
  • Association Data: Complex entity relationships with sub-associations
  • Legacy ID Support: Handles both legacyID and legacyIDV2 formats
  • Edge-based Results: GraphQL edges/nodes pattern

…