Custom Fields API: Extending QuickBooks Online with flexible metadata -

Every business is unique, and sometimes the standard fields in QuickBooks Online aren’t enough to capture the details that matter most. Whether it’s tracking project codes, industry-specific identifiers or customer preferences, developers need a way to extend QuickBooks data models without workarounds.

That’s exactly what the Custom Fields API delivers. Announced as part of Intuit’s new Premium APIs for Gold and Platinum partners, this feature lets you define and manage flexible metadata that can be applied across entities such as customers, invoices and vendors.

Click here to learn more about the different partner tiers and how to upgrade.

In this post, we’ll walk through

Why Custom Fields matter
How the API works (GraphQL + REST)
Example workflows for adding custom fields to invoices and customers
Best practices and limitations
Resources to get you started

Why Custom Fields matter

Custom fields unlock a wide range of business scenarios:

Invoices: Tag sales with project codes, contract IDs or internal categories
Customers: Track type, sales region or loyalty tier
Vendors: Record supplier contract numbers or reference IDs

Instead of relying on external spreadsheets or manual tracking, you can now embed this metadata directly in QuickBooks Online, making it easier to query, report and automate workflows.

For more inspiration, explore the Custom Fields use cases.

How the API works

The Custom Fields API combines two layers:

1. Define Custom Fields (GraphQL)

Custom field definitions are created and managed through GraphQL. This is where you decide what fields exist, their types and which entities they apply to. Required OAuth scopes include:

app-foundations.custom-field-definitions.read — read-only access
app-foundations.custom-field-definitions — read & write access
com.intuit.quickbooks.accounting — for REST interactions alongside metadata

Endpoint: https://qb.api.intuit.com/graphql

Example query: Retrieve custom field definitions

query {
  appFoundationsCustomFieldDefinitions {
    id
    name
    type
    legacyIdV2
  }
}

Example mutation: Create a new Custom Field definition

mutation {
  appFoundationsCreateCustomFieldDefinition(
    input: { name: "ProjectCode", type: StringType }
  ) {
    customFieldDefinition {
      id
      name
      type
      legacyIdV2
    }
  }
}

2. Apply Custom Fields (REST)

Once defined, custom fields are attached to transactions and entities using the QuickBooks Online Accounting REST API.

Endpoint pattern:

https://quickbooks.api.intuit.com/v3/company/{realmId}/{entity}?minorversion=75&include=enhancedAllCustomFields

Required headers:

Authorization: Bearer <access_token>
Content-Type: application/json

Workflow examples

Example 1: Add a Custom Field to an invoice

Retrieve or create a custom field definition via GraphQL
Note the legacyIdV2 (maps to DefinitionId in REST)
Create an invoice with the custom field attached

{
  "Line": [
    {
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": { "value": "1", "name": "Services" }
      }
    }
  ],
  "CustomerRef": { "value": "1" },
  "CustomField": [
    {
      "DefinitionId": "1",
      "StringValue": "Project-123"
    }
  ]
}

Example 2: Add a Custom Field to a customer

{
  "DisplayName": "Customer-01",
  "CustomField": [
    {
      "DefinitionId": "540344",
      "StringValue": "Enterprise"
    }
  ]
}

Sample app reference

Explore the Intuit Developer sample repositories for hands-on examples:

OAuth setup and scope configuration
Creating and managing custom fields
Parsing metadata in REST responses

Browse sample repos

Limitations & considerations

No sandbox support: Testing requires a production QuickBooks company
Partner tiers: Only Gold and Platinum partners can access this API
Inactive fields: Deactivating a field does not remove historical data

Best practices

Define fields once and reuse across entities
Use meaningful, consistent naming
Validate input values to maintain clean reporting
Use production companies for real-world testing

The final note

The Custom Fields API brings powerful flexibility to QuickBooks Online by allowing developers to extend core objects with business-specific metadata. Use GraphQL to define fields and REST to apply them across invoices, customers, vendors and more.

Getting started by partner tier

Builder and Silver: Click here to upgrade
Gold & Platinum: Enable required scopes in the developer portal under Permissions

Custom Fields API: Extending QuickBooks Online with flexible metadata