RecordBuilder

The `RecordBuilder` offers a fluent, generic way to construct JSON payloads for any Acumatica entity—customers, orders, stock items, etc.—without manual nesting or merging. It is the most flexible builder in the library.

Importing the Builder

To get started, import the `RecordBuilder` from the `easy_acumatica.models` module.


from easy_acumatica.models.record_builder import RecordBuilder

Core Methods

.field(name, value)

Sets a simple data field, automatically wrapping it in the required `{"value": ...}` structure.

rb = RecordBuilder().field('CustomerID', 'CUST100')

.link(name)

Navigates into a linked entity block (e.g., `BillTo` address). This returns a new child builder, allowing you to set fields on the nested object. Use `.up()` to return to the parent.


rb = RecordBuilder()
rb.link("BillTo") \
  .field("LocationID", "MAIN") \
  .field("AddressLine1", "123 Elm St") \
  .up() # back to root

.add_detail(name)

Appends a new line item to a detail list (e.g., `OrderLines`). This returns a new builder scoped to that specific line, allowing you to set its fields.


order = RecordBuilder().field("OrderType", "SO")

# Add first order line
order.add_detail("OrderLines") \
     .field("InventoryID", "ABC123") \
     .field("Quantity", 5)

# The builder is now scoped to the line; .up() is not needed
# to add another line to the same detail list.
order.add_detail("OrderLines") \
     .field("InventoryID", "XYZ789") \
     .field("Quantity", 2)

.custom(view, field, value, ...)

Sets user-defined or custom fields, creating the nested `custom` block in the JSON payload.


rb = RecordBuilder()
rb.custom(
    "SalesOrderEntry", 
    "UsrPriority", 
    value="High", 
    type_="CustomStringField"
)