Easy-Acumatica Docs

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.

python

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`.

python

# 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.

python

# 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.

python

# 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.

python

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.

python

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.

python

# 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'
)
Easy-Acumatica v0.3.9 — Created and Developed by Matthew Hirstius (Nioron07).
Significant Contributions made by Chris Xu
Want to see the NPM version? See it here