This guide covers the CustomersService, which is your primary tool for interacting with Customer records through the contract-based API.

1. Importing Helpers

Before you start, import the necessary helpers for building queries and customer payloads.

from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions, CustomField  
from easy_acumatica.models.customer_builder import CustomerBuilder

2. Retrieving Customers

get_customers(api_version, options=None)

This is the main method for fetching a list of customer records. It can be used to get all customers or a filtered, specific list by using QueryOptions.

Example: Get all active customers

# Create a filter for active customers  
my_filter = (F.Status == 'Active')

# Use QueryOptions to select specific fields and expand the billing contact  
opts = QueryOptions(  
    filter=my_filter,  
    select=["CustomerID", "CustomerName", "BillingContact/Email"],  
    expand=["BillingContact"]  
)

# Fetch the customers  
active_customers = client.customers.get_customers("24.200.001", options=opts)

for customer in active_customers:  
    print(f"ID: {customer['CustomerID']['value']}, Name: {customer['CustomerName']['value']}")

3. Creating and Updating Customers

create_customer(api_version, builder)

Use this method to create a new customer record. You must provide a CustomerBuilder object containing the new customer's details.

Example: Create a new customer

# Build the customer payload  
customer_payload = (  
    CustomerBuilder()  
    .customer_id("NEWCUST01")  
    .customer_name("New Innovations Inc.")  
    .customer_class("DEFAULT")  
)

# Create the customer  
new_customer = client.customers.create_customer("24.200.001", customer_payload)  
print(f"Successfully created customer with ID: {new_customer['CustomerID']['value']}")

update_customer(api_version, builder, options)

Use this method to update one or more existing customers. You must provide a filter in the options to specify which customer(s) to update.

Example: Update a customer's class based on their email

# Find the customer with a specific email address  
update_filter = F.MainContact.Email == '[email protected]'  
opts = QueryOptions(filter=update_filter)

# Define the fields to update  
update_payload = CustomerBuilder().set("CustomerClass", "INTL")

# Perform the update  
updated_customer = client.customers.update_customer("24.200.001", update_payload, options=opts)

4. Specialized Helper Methods

The CustomersService also includes several helpers for common, specific tasks.

assign_tax_zone(api_version, customer_id, tax_zone)

Assigns a specific tax zone to a customer.

client.customers.assign_tax_zone(  
    "24.200.001",  
    customer_id="NEWCUST01",  
    tax_zone="AVATAX"  
)

get_shipping_contact(api_version, customer_id)

A convenient shortcut to retrieve just the ShippingContact object for a single customer. Returns the contact dictionary or None if not found.

shipping_info = client.customers.get_shipping_contact(  
    "24.200.001",  
    customer_id="NEWCUST01"  
)

if shipping_info:  
    print(f"Shipping Contact Email: {shipping_info.get('Email', {}).get('value')}")

update_customer_currency_overriding(api_version, customer_id, enable, currency_rate_type='SPOT')

Enables or disables the ability to override currency and exchange rates for a specific customer.

Enable currency overriding for a customer

client.customers.update_customer_currency_overriding(  
    "24.200.001",  
    customer_id="NEWCUST01",  
    enable=True,  
    currency_rate_type="SPOT" # Optional, defaults to 'SPOT'  
)