This guide covers the RecordsService, which is a powerful, generic wrapper for performing CRUD (Create, Read, Update, Delete) operations on any top-level Acumatica entity, such as StockItem, SalesOrder, or PurchaseOrder.

1. Accessing the Service

The RecordsService is available as an attribute on your main AcumaticaClient instance.

Assuming 'client' is an initialized AcumaticaClient

records_service = client.records

2. Retrieving Records

The service provides three methods for fetching records based on different criteria.

get_records_by_filter(api_version, entity, options, show_archived=False)

This is the most flexible method for querying records. It requires a QueryOptions object with a $filter to find records matching specific criteria.

Example: Find all "Finished Good" stock items that are low on inventory.

from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions

# Define a filter for finished goods with quantity on hand less than 10  
low_stock_filter = (F.ItemClass.ID == 'FINISHGOOD') & (F.QtyOnHand < 10)

# Use QueryOptions to select specific fields and apply the filter  
opts = QueryOptions(  
    filter=low_stock_filter,  
    select=["InventoryID", "Description", "QtyOnHand"],  
    expand=["ItemClass"] # Optional: expand related entities  
)

# Fetch the records, including any archived items  
low_stock_items = client.records.get_records_by_filter(  
    "24.200.001",  
    entity="StockItem",  
    options=opts,  
    show_archived=True  
)

for item in low_stock_items:  
    print(f"Item: {item['InventoryID']['value']}, Qty: {item['QtyOnHand']['value']}")

get_record_by_id(api_version, entity, id, options=None)

Retrieves a single record using its internal Acumatica GUID (id).

# Get a specific sales order by its ID  
sales_order = client.records.get_record_by_id(  
    "24.200.001",  
    entity="SalesOrder",  
    id="a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6"  
)

get_record_by_key_field(api_version, entity, key, value, options=None)

Retrieves a single record using its primary key fields, which are often composite (e.g., Order Type and Order Number).

# Get a Sales Order of type 'SO' with number 'SO006724'  
sales_order = client.records.get_record_by_key_field(  
    "24.200.001",  
    entity="SalesOrder",  
    key="SO",  
    value="SO006724"  
)

3. Creating Records

create_record(api_version, entity, record, options=None)

Creates a new record for any entity. You must provide the payload using the RecordBuilder.

Example: Create a new non-stock item.

from easy_acumatica.models.record_builder import RecordBuilder

# Use RecordBuilder to construct the payload  
non_stock_item = (  
    RecordBuilder()  
    .field("InventoryID", "CONSULT-HR")  
    .field("Description", "HR Consulting Services")  
    .field("ItemClass", "NONSTOCK")  
    .field("DefaultPrice", 250.00)  
)

# Call the service to create the record  
new_item = client.records.create_record(  
    "24.200.001",  
    entity="NonStockItem",  
    record=non_stock_item  
)  
print(f"Created item with ID: {new_item['InventoryID']['value']}")

4. Updating Records

update_record(api_version, entity, record, options)

Updates one or more existing records. You must provide a filter in the options to specify which record(s) to update.

Example: Update the description of a specific stock item.

from easy_acumatica.models.record_builder import RecordBuilder  
from easy_acumatica.models.filter_builder import F  
from easy_acumatica.models.query_builder import QueryOptions

# Specify which record to update using a filter  
update_opts = QueryOptions(filter=(F.InventoryID == 'CONSULT-HR'))

# Define the fields to change using a RecordBuilder  
update_payload = RecordBuilder().field("Description", "Human Resources Consulting - Premier")

# Perform the update  
updated_item = client.records.update_record(  
    "24.200.001",  
    entity="NonStockItem",  
    record=update_payload,  
    options=update_opts  
)

5. Deleting Records

delete_record_by_id(api_version, entity, record_id)

Permanently deletes a record using its internal GUID.

# Delete a sales order by its ID  
client.records.delete_record_by_id(  
    "24.200.001",  
    entity="SalesOrder",  
    record_id="a1b2c3d4-e5f6-a7b8-c9d0-e1f2a3b4c5d6"  
)

delete_record_by_key_field(api_version, entity, key, value)

Permanently deletes a record using its primary key fields.

# Delete a sales order by its type and number  
client.records.delete_record_by_key_field(  
    "24.200.001",  
    entity="SalesOrder",  
    key="SO",  
    value="SO006724"  
)  

5. Discovering Custom Fields

get_custom_field_schema(api_version, entity)

A powerful introspection tool that retrieves the schema for all custom and user-defined fields associated with an entity. This is useful for dynamically building integrations.

Example: Get the custom field schema for the StockItem entity.

try:  
    schema = client.records.get_custom_field_schema(  
        "24.200.001",  
        entity="StockItem"  
    )  
    # The 'schema' variable now holds a dictionary detailing all custom fields,  
    # including their names, view names, and types.  
    print(schema)  
except Exception as e:  
    print(f"Failed to retrieve schema: {e}")