Customer Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the CustomerBuilder, which is your primary tool for creating the JSON payload needed to create or update Customer records with the CustomersService.

1. Importing the CustomerBuilder

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

from easy_acumatica.models.customer_builder import CustomerBuilder

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: {"value": ...}. The CustomerBuilder handles this formatting for you automatically, so you can focus on the data itself.

The builder provides a fluent, chainable interface for setting the fields of a customer record.

3. Building a Customer Payload

You can set fields using either the generic .set() method or one of the convenient shortcut methods.

set(field_name, value)

This is the general-purpose method for setting any field on the customer record.

# Create a builder instance  
customer_payload = CustomerBuilder()

# Use the .set() method for any field  
customer_payload.set("CreditLimit", 5000.0)  
customer_payload.set("Status", "Active")

Shortcut Methods

For common fields, you can use one of the built-in shortcut methods for a cleaner syntax.

• .customer_id(id)
• .customer_name(name)
• .customer_class(class)

Example: Using shortcut methods

customer_payload = (  
    CustomerBuilder()  
    .customer_id("CUST001")  
    .customer_name("Global Tech Inc.")  
    .customer_class("DEFAULT")  
)

4. Generating the Final JSON Body

Once you have set all the required fields, call the .to_body() method to generate the final dictionary. This dictionary is formatted correctly and is ready to be sent as the JSON body in your API request.

# Build the customer  
customer_payload = (  
    CustomerBuilder()  
    .customer_id("CUST001")  
    .customer_name("Global Tech Inc.")  
    .customer_class("DEFAULT")  
    .set("Status", "Active")  
)

# Get the final dictionary  
json_body = customer_payload.to_body()

# The json_body will look like this:  
# {  
#     "CustomerID": {"value": "CUST001"},  
#     "CustomerName": {"value": "Global Tech Inc."},  
#     "CustomerClass": {"value": "DEFAULT"},  
#     "Status": {"value": "Active"}  
# }

5. Complete Example with CustomersService

Here is a complete example of how to use the CustomerBuilder to create a new customer.

from easy_acumatica.models.customer_builder import CustomerBuilder

# 1. Build the customer payload  
customer_to_create = (  
    CustomerBuilder()  
    .customer_id("INNOTECH")  
    .customer_name("Innovation Technologies")  
    .customer_class("HIGHVOL")  
    .set("Status", "Active")  
)

# 2. Use the payload with the CustomersService to create the record  
try:  
    new_customer = client.customers.create_customer(  
        "24.200.001",  
        builder=customer_to_create  
    )  
    print(f"Successfully created customer: {new_customer['CustomerID']['value']}")  
except Exception as e:  
    print(f"Failed to create customer: {e}")