Quickstart Guide

Get started with Easy-Acumatica v0.5.4

Prerequisites

Easy-Acumatica v0.5.4 installed (pip install easy-acumatica)
Acumatica instance with REST API enabled
API credentials (username, password, tenant, branch)

Configuration

Create a .env file in your project root:

ACUMATICA_URL=https://your-instance.acumatica.com
ACUMATICA_USERNAME=your-username
ACUMATICA_PASSWORD=your-password
ACUMATICA_TENANT=your-tenant
ACUMATICA_BRANCH=MAIN
ACUMATICA_CACHE_METHODS=true
ACUMATICA_CACHE_TTL_HOURS=24

Initialize Client

The client automatically loads credentials from your .env file:

from easy_acumatica import AcumaticaClient

# Automatically loads from .env
client = AcumaticaClient()

# Or specify credentials manually
client = AcumaticaClient(
    base_url="https://your-instance.acumatica.com",
    username="your_username",
    password="your_password",
    tenant="YourTenant",
    branch="MAIN"
)

On initialization, the client discovers all available endpoints and generates corresponding services and models.

Basic CRUD Operations

Read Data

# Get all customers
customers = client.customers.get_list()

# Get customer by ID
customer = client.customers.get_by_id("CUST001")

# Get customer by key fields
customer = client.customers.get_by_keys(CustomerID="CUST001")

Create Data

# Create a new customer
new_customer = client.models.Customer(
    CustomerID="CUST001",
    CustomerName="Acme Corporation",
    Email="contact@acmecorp.com",
    Phone="555-0123"
)

result = client.customers.put_entity(new_customer)
print(f"Created customer: {result.CustomerID}")

Update Data

# Get existing customer
customer = client.customers.get_by_id("CUST001")

# Update fields
customer.Email = "newemail@acmecorp.com"
customer.Phone = "555-9999"

# Save changes
updated = client.customers.put_entity(customer)

Delete Data

# Delete by ID
client.customers.delete_by_id("CUST001")

# Delete by key fields
client.customers.delete_by_keys(CustomerID="CUST001")

Querying with OData

Use QueryOptions and the F filter factory for complex queries:

from easy_acumatica.odata import QueryOptions, F

# Simple filter
options = QueryOptions(
    filter=F.Status == "Active"
)
active_customers = client.customers.get_list(options=options)

# Complex filter
options = QueryOptions(
    filter=(F.Status == "Active") & (F.CreditLimit > 10000),
    select=["CustomerID", "CustomerName", "CreditLimit"],
    orderby=["CustomerName"],
    top=50
)
customers = client.customers.get_list(options=options)

Working with Related Data

Use expand to include related entities:

from easy_acumatica.odata import QueryOptions, F

# Get sales orders with details and customer information
options = QueryOptions(
    filter=F.Status == "Open",
    expand=["Details", "Customer"],
    orderby=["Date desc"]
)
orders = client.sales_orders.get_list(options=options)

# Access expanded data
for order in orders:
    print(f"Order: {order.OrderNbr}")
    print(f"Customer: {order.Customer.CustomerName}")
    for detail in order.Details:
        print(f"  Item: {detail.InventoryID}, Qty: {detail.Quantity}")

Custom Actions

Execute custom actions defined in your Acumatica instance:

# Check if action exists
if hasattr(client.invoices, 'invoke_action_release'):
    # Get the invoice
    invoice = client.invoices.get_by_id("INV001234")

    # Execute the release action
    client.invoices.invoke_action_release(entity=invoice)
    print(f"Released invoice {invoice.RefNbr}")

Complete Example

A practical example combining multiple operations:

from easy_acumatica import AcumaticaClient
from easy_acumatica.odata import QueryOptions, F
from datetime import datetime, timedelta

# Initialize client
client = AcumaticaClient()

# Get recent completed orders
end_date = datetime.now()
start_date = end_date - timedelta(days=30)

options = QueryOptions(
    filter=(F.Status == "Completed") & (F.Date >= start_date),
    expand=["Details", "Customer"],
    orderby=["Date desc"]
)
completed_orders = client.sales_orders.get_list(options=options)

# Process each order
for order in completed_orders:
    # Check if invoice already exists
    invoice_check = QueryOptions(
        filter=(F.CustomerID == order.CustomerID) &
               (F.Description.contains(order.OrderNbr))
    )
    existing = client.invoices.get_list(options=invoice_check)

    if existing:
        print(f"Invoice exists for order {order.OrderNbr}")
        continue

    # Create invoice from order
    invoice = client.models.Invoice(
        CustomerID=order.CustomerID,
        Date=datetime.now().strftime('%Y-%m-%d'),
        Description=f"Invoice for Order {order.OrderNbr}",
        Details=[
            client.models.InvoiceDetail(
                InventoryID=detail.InventoryID,
                Quantity=detail.Quantity,
                UnitPrice=detail.UnitPrice
            )
            for detail in order.Details
        ]
    )

    # Create and release invoice
    created = client.invoices.put_entity(invoice)
    print(f"Created invoice {created.RefNbr} for order {order.OrderNbr}")

    if hasattr(client.invoices, 'invoke_action_release'):
        client.invoices.invoke_action_release(entity=created)
        print(f"Released invoice {created.RefNbr}")

Next Steps

Client Configuration - Advanced client options and features
Dynamic Services - Service methods and patterns
Model Factory - Working with dynamic models
OData Queries - Advanced filtering and querying

On this page