QuickBooks: Create a category

← item operations · Get started · OpenAPI downloads

Contract 2026-10-20 · Operation quickbooks.item.create_a_category

Provider route: POST /v3/company/{realmID}/item. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/quickbooks with npm, or alter-sdk-quickbooks with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { QuickBooksIntegration } from "@alter-ai/quickbooks";

async function execute(input: Parameters<QuickBooksIntegration["item"]["createCategory"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new QuickBooksIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.item.createCategory(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_quickbooks import QuickBooksIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = QuickBooksIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.item.create_category(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Optional	Additional keys: not allowed
query.minorversion	integer	Optional	Must equal: 75
query.requestid	string	Optional	Minimum length: 1
body	object	Required within parent	Fields not accepted: Id, SyncToken Additional keys: not allowed
body.Active	JSON	Optional	If true, the object is currently enabled for use by QuickBooks.
body.Active (anyOf 1)	boolean	Alternative
body.Active (anyOf 2)	string	Alternative	One of: true, false
body.AssetAccountRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the Inventory Asset account that tracks the current value of the inventory. If the same account is used for all inventory items, the current balance of this account will represent the current total value of the inventory. Query the Account name list resource to determine the appropriate Account object for this reference. Use Account.Id and Account.Name from that object for AssetAccountRef.value and AssetAccountRef.name , respectively. Required for Inventory item types. Conditionally required
body.ClassRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the Class for the item. Query the Class name list resource to determine the appropriate object for this reference. Use Class.Id and Class.Name from that object for ClassRef.value and ClassRef.name , respectively.
body.CustomExtensions	Model	Optional	Expand Create an item — request body — body Custom Extensions Array of custom extension objects that associate additional attributes with the item. The ExtensionType field specifies the type of extension. The currently supported value is DIMENSION . The AssociatedValues array contains key/value pairs referencing Dimensions DefinitionID/Dimension ValueID. Multiple key/value pairs per extension type are supported. This field is designed to support additional extension types in the future. Dimensions is available for Intuit Enterprise Suite.
body.Description	string	Optional	Description of the item.
body.ExpenseAccountRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the expense account used to pay the vendor for this item. Must be an account with account type of Cost of Goods Sold . Query the Account name list resource to determine the appropriate Account object for this reference. Use Account.Id and Account.Name from that object for ExpenseAccountRef.value and ExpenseAccountRef.name , respectively. Required for Inventory , NonInventory , and Service item types.
body.FullyQualifiedName	string	Optional	Fully qualified name of the entity. The fully qualified name prepends the topmost parent, followed by each sub element separated by colons. Takes the form of Item:SubItem . Returned from an existing object and not input on a new object.Limited to 5 levels. Read only: true
body.IncomeAccountRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the posting account, that is, the account that records the proceeds from the sale of this item. Must be an account with account type of Sales of Product Income . Query the Account name list resource to determine the appropriate Account object for this reference. Use Account.Id and Account.Name from that object for IncomeAccountRef.value and IncomeAccountRef.name , respectively. Required for Inventory and Service item types.
body.InvStartDate	string	Optional	Date of opening balance for the inventory transaction. For read operations, the date returned in this field is always the originally provided inventory start date. For update operations, the date supplied is interpreted as the inventory adjust date, is stored as such in the underlying data model, and is reflected in the QuickBooks Online UI for the object. The inventory adjust date is not exposed for read operations through the API. Required for Inventory type items. Conditionally required
body.Level	JSON	Optional	Specifies the level of the hierarchy in which the entity is located. Zero specifies the top level of the hierarchy; anything above will be the next level with respect to the parent. Limited to 5 levels. Read only: true
body.Level (anyOf 1)	integer	Alternative
body.Level (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+$
body.MetaData	Model	Optional	Expand Read a bill — response body — Bill Meta Data Descriptive information about the entity. The MetaData values are set by Data Services and are read only for all applications.
body.Name	string	Required within parent	Name of the category.
body.ParentRef	Model	Optional	Expand Create a purchase order — request body — body Ship To The immediate parent of the sub item in the hierarchical Category:Sub-category list. If SubItem is true, then ParenRef is required. Query the Item name list resource to determine the appropriate object for this reference. Use Item.Id and Item.Name from that object for ParentRef.value and ParentRef.name , respectively. Conditionally required
body.PrefVendorRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the preferred vendor of this item. Query the Vendor name list resource to determine the appropriate object for this reference. Use Vendor.Id and Vendor.Name from that object for ParentRef.value and ParentRef.name , respectively.
body.PurchaseCost	JSON	Optional	Amount paid when buying or ordering the item, as expressed in the home currency. Decimal string
body.PurchaseCost (anyOf 1)	number	Alternative
body.PurchaseCost (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.PurchaseDesc	string	Optional	Purchase description for the item.
body.PurchaseTaxCodeRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Reference to the purchase tax code for the item. Applicable to Service, Other Charge, and Product (Non-Inventory) item types. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for PurchaseTaxCodeRef.value and PurchaseTaxCodeRef.name , respectively.
body.PurchaseTaxIncluded	JSON	Optional	True if the purchase tax is included in the item amount, and therefore is not calculated for the transaction.
body.PurchaseTaxIncluded (anyOf 1)	boolean	Alternative
body.PurchaseTaxIncluded (anyOf 2)	string	Alternative	One of: true, false
body.QtyOnHand	JSON	Optional	Current quantity of the Inventory items available for sale. Not used for Service or NonInventory type items.Required for Inventory type items. Conditionally required Decimal string
body.QtyOnHand (anyOf 1)	number	Alternative
body.QtyOnHand (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.ReorderPoint	JSON	Optional	The minimum quantity of a particular inventory item that you need to restock at any given time. The ReorderPoint value cannot be set to null for sparse updates(sparse=true). It can be set to null only for full updates. Decimal string
body.ReorderPoint (anyOf 1)	number	Alternative
body.ReorderPoint (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.SalesTaxCodeRef	Model	Optional	Expand Create a purchase order — request body — body Ship To For non-US companies only. Reference to the sales tax code for the Sales item. Applicable to Service and Sales item types only. Query the TaxCode name list resource to determine the appropriate TaxCode object for this reference. Use TaxCode.Id and TaxCode.Name from that object for SalesTaxCodeRef.value and SalesTaxCodeRef.name , respectively.
body.SalesTaxIncluded	JSON	Optional	True if the sales tax is included in the item amount, and therefore is not calculated for the transaction.
body.SalesTaxIncluded (anyOf 1)	boolean	Alternative
body.SalesTaxIncluded (anyOf 2)	string	Alternative	One of: true, false
body.Sku	string	Optional	The stock keeping unit (SKU) for this Item. This is a company-defined identifier for an item or product used in tracking inventory.
body.Source	string	Optional	The Source type of the transactions created by QuickBooks Commerce. Valid values include: QBCommerce
body.SubItem	JSON	Optional	true —The object is a sub-category. false —The object is a top-level category (default). Sub-categories can be nested to a maximum depth of three levels below a top-level category. Required for sub-category. Conditionally required
body.SubItem (anyOf 1)	boolean	Alternative
body.SubItem (anyOf 2)	string	Alternative	One of: true, false
body.TaxClassificationRef	Model	Optional	Expand Create a purchase order — request body — body Ship To Tax classification segregates different items into different classifications and the tax classification is one of the key parameters to determine appropriate tax on transactions involving items. Tax classifications are sourced by either tax governing authorities as in Malaysia or externally like Exactor. ‘Fuel’, ‘Garments’ and ‘Soft drinks’ are a few examples of tax classification in layman terms. User can choose a specific tax classification for an item while creating it. A level 1 tax classification cannot be associated to an Item.
body.Taxable	JSON	Optional	If true, transactions for this item are taxable. Applicable to US companies, only.
body.Taxable (anyOf 1)	boolean	Alternative
body.Taxable (anyOf 2)	string	Alternative	One of: true, false
body.TrackQtyOnHand	JSON	Optional	True if there is quantity on hand to be tracked. Once this value is true, it cannot be updated to false. Applicable for items of type Inventory . Not applicable for Service or NonInventory item types.
body.TrackQtyOnHand (anyOf 1)	boolean	Alternative
body.TrackQtyOnHand (anyOf 2)	string	Alternative	One of: true, false
body.Type	string	Required within parent	Must be set to the literal string, Category .
body.UnitPrice	JSON	Optional	Corresponds to the Price/Rate column on the QuickBooks Online UI to specify either unit price, a discount, or a tax rate for item. If used for unit price, the monetary value of the service or product, as expressed in the home currency. If used for a discount or tax rate, express the percentage as a fraction. For example, specify 0.4 for 40% tax. Decimal string
body.UnitPrice (anyOf 1)	number	Alternative
body.UnitPrice (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?$
body.domain	string	Optional
body.sparse	boolean	Optional

Referenced models: Read a bill — response body — Bill Meta Data, Create an item — request body — body Custom Extensions, Create a purchase order — request body — body Ship To

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: allowed
time	string	Optional
Item	Model	Optional	Expand Create a category — response body — Item

Referenced models: Create a category — response body — Item

Policy, approvals and errors

SDK function policy ID: quickbooks.item.create_a_category. Catalog operation: items/create. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source