Tax Category Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the TaxCategoryBuilder, which is your primary tool for creating the JSON payload needed to create or update TaxCategory records.

1. Importing the Builder

To get started, import the TaxCategoryBuilder from the models directory.

from easy_acumatica.models.tax_category_builder import TaxCategoryBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure, such as {"value": ...}. The TaxCategoryBuilder handles this formatting for you automatically, allowing you to construct a valid payload for a new tax category using a fluent, chainable interface.

3. TaxCategoryBuilder Methods

The following table summarizes the methods available in the TaxCategoryBuilder.

Method	Description	Key Parameters
.set()	Sets any top-level field on the tax category.	field (str), value (Any)
.tax_category_id()	(Required) Sets the TaxCategoryID.	taxCategoryID (str)
.description()	Sets the Description of the tax category.	description (str)
.active()	Sets the Active status.	isActive (bool)
.exclude_listed_taxes()	Sets the ExcludeListedTaxes flag.	excludeListedTaxes (bool)
.note()	Sets a note for the tax category.	note (str)
.to_body()	Constructs the final JSON payload for the request.	(None)

4. Building a Tax Category Payload

You can use the builder's methods to construct the payload for the new tax category.

Example: Creating a tax category

# 1. Create a builder instance
tax_category_payload = (
    TaxCategoryBuilder()
    .tax_category_id("SERVICES")
    .description("Taxable Services")
    .active(True)
    .exclude_listed_taxes(False)
    .note("Default tax category for all service items.")
)

5. Generating the Final JSON Body

Once you have configured the builder, call the .to_body() method to generate the final dictionary.

# 1. Build the tax category
tax_category_payload = (
    TaxCategoryBuilder()
    .tax_category_id("EXEMPT")
    .description("Non-taxable items")
    .active(True)
)

# 2. Get the final dictionary
json_body = tax_category_payload.to_body()

# The json_body will look like this:
# {
#   "TaxCategoryID": {"value": "EXEMPT"},
#   "Description": {"value": "Non-taxable items"},
#   "Active": {"value": True}
# }

6. Complete Example with a TaxCategoryService

Here is a complete example of how to use the TaxCategoryBuilder to create a new tax category record.

from easy_acumatica.models.tax_category_builder import TaxCategoryBuilder

# 1. Build the tax category payload
tax_category_to_create = (
    TaxCategoryBuilder()
    .tax_category_id("GOODS")
    .description("Taxable Goods")
    .active(True)
    .exclude_listed_taxes(False)
)

# 2. Use the payload with the TaxCategoryService to create the record
try:
    new_category = client.tax_categories.update_tax_category(
        "24.200.001",
        builder=tax_category_to_create
    )
    print(f"Successfully created tax category: {new_category['TaxCategoryID']['value']}")
except Exception as e:
    print(f"Failed to create tax category: {e}")