Customers Sub Service - Nioron07/Easy-Acumatica GitHub Wiki
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'
)