Customers Service
The `CustomersService` is your primary tool for interacting with Customer records through the contract-based API. It provides methods to create, retrieve, and update customer data, as well as several specialized helpers for common tasks.
Importing Helpers
Before using the service, you should import the necessary builders and query helpers from the `easy_acumatica.models` module.
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
Core Methods
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`.
# Create a filter for active customers
my_filter = (F.Status == 'Active')
# Use QueryOptions to select specific fields and expand related data
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)
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.
# 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)
update_customer(api_version, builder, options)
Use this method to update one or more existing customers. You must provide a filter in the `options` object to specify which customer(s) to update.
# Define a filter to find the customer to update
update_filter = F.MainContact.Email == 'test@newinnovations.com'
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
)
Specialized Helpers
assign_tax_zone(...)
A shortcut method to assign a specific tax zone to a customer.
client.customers.assign_tax_zone(
"24.200.001",
customer_id="NEWCUST01",
tax_zone="AVATAX"
)
get_shipping_contact(...)
A convenient helper to retrieve just the `ShippingContact` object for a single customer. It 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(shipping_info.get('Email', {}).get('value'))
update_customer_currency_overriding(...)
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'
)