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.
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
Update your
Note: The App Foundations Custom Field Definitions API uses the production environment by default as it's not available in sandbox mode.
Prerequisites
Before running this application, ensure you have the following:
Required Versions:
Copy the ngrok URL and update your
The App Foundations API provides advanced custom field capabilities:
Data Types
Custom fields can be associated with different QuickBooks entities and their sub-types. The API supports flexible association configurations:
*Supported Entity Types*
*Association Features*
The service uses the App Foundations API with complete CRUD support:
*Queries*
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_CustomFieldDefinitionInputschema 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
GET /api/quickbook/custom-fields- Get all custom field definitions with associationsPOST /api/quickbook/custom-fields- Create a new custom field definitionPUT /api/quickbook/custom-fields/:id- Update an existing custom field definitionDELETE /api/quickbook/custom-fields/:id- Delete (deactivate) a custom field definition
GET /api/auth/login- Initiate OAuth flowGET /api/auth/callback- OAuth callback handlerPOST /api/auth/retrieveToken- Get current token information
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/callbackPrerequisites
Before running this application, ensure you have the following:
- Node.js 18.0.0 or higher - Download Node.js
- npm 8.0.0 or higher - Comes with Node.js
- ngrok - For OAuth callback handling - Download ngrok
- A QuickBooks Online Developer Account
- An application created in the Intuit Developer Portal
node --version
npm --versionRequired Versions:
- Node.js: 18.0.0 or higher
- npm: 8.0.0 or higher
- Install Dependencies
npm install
- Configure QuickBooks App
- Create a QuickBooks app at Intuit Developer
- Update
.envwith your app credentials - Set redirect URI to your ngrok URL:
https://your-ngrok-url.ngrok-free.app/api/auth/callback
- Start ngrok (Required for OAuth)
ngrok http 8080Copy the ngrok URL and update your
.env file and QuickBooks app settings.
- Run the Application
npm start
- Access the Application
- Open your browser to
http://localhost:8080 - Click "Connect to QuickBooks" to authenticate
- Use the interface to manage custom fields
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)
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 invoicesSALE_ESTIMATE- Sales estimates/quotesPURCHASE_ORDER- Purchase orders- And more transaction types...
- Contacts:
/network/Contact CUSTOMER- Customer contactsVENDOR- Vendor contactsEMPLOYEE- Employee contacts
{
"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:
INCLUDEDorEXCLUDEDassociation conditions - ❌ Mixed Entity Types: Cannot combine Contact and Transaction associations in one field
- 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)
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
legacyIDandlegacyIDV2formats - Edge-based Results: GraphQL edges/nodes pattern