Stock Item Builder - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the StockItemBuilder, which is your primary tool for creating the JSON payload needed to create or update StockItem records with the StockItemsService.

1. Importing the StockItemBuilder

To get started, import the StockItemBuilder from the models directory.

from easy_acumatica.models.stock_item_builder import StockItemBuilder

2. Understanding the Builder's Purpose

When you send data to Acumatica's contract-based API, each field must be wrapped in a specific JSON structure, such as {"value": ...}. The StockItemBuilder handles this formatting for you automatically, allowing you to construct a valid payload using a fluent, chainable interface.

3. StockItemBuilder Methods

The following table summarizes the primary methods available in the StockItemBuilder.

Method	Description	Parameters
`.set()`	Sets any top-level field on the stock item.	`field` (str), `value` (Any)
`.inventory_id()`	(Required) Sets the `InventoryID`.	`id` (str)
`.description()`	Shortcut for setting the `Description`.	`description` (str)
`.item_class()`	Shortcut for setting the `ItemClass`.	`item_class` (str)
`.note()`	Sets the `note` field for the item.	`note` (str)
`.add_attribute()`	Adds an attribute line to the item.	`attribute_id` (str), `value` (str)
`.to_body()`	Constructs the final JSON payload.	(None)

4. Building a Stock Item Payload

You can set top-level fields using the generic .set() method or one of the convenient shortcut methods.

Adding Attributes

The .add_attribute() method allows you to add attribute lines to the item. You can chain this method to add multiple attributes.

Example: Building a complete stock item

# 1. Create a builder instance
item_payload = (
    StockItemBuilder()
    .inventory_id("NEW-ITEM-003")
    .description("A new item with several attributes")
    .item_class("FINISHED")
    .note("Internal note about sourcing.")
    .add_attribute(attribute_id="COLOR", value="Green")
    .add_attribute(attribute_id="SIZE", value="Medium")
    .add_attribute(attribute_id="MATERIAL", value="Cotton")
)

5. Generating the Final JSON Body

Once you have set all the required fields, call the .to_body() method to generate the final dictionary.

# 1. Build the item
item_payload = (
    StockItemBuilder()
    .inventory_id("NEW-ITEM-003")
    .description("A new item")
    .add_attribute(attribute_id="COLOR", value="Green")
)

# 2. Get the final dictionary
json_body = item_payload.to_body()

# The json_body will look like this:
# {
#     "InventoryID": {"value": "NEW-ITEM-003"},
#     "Description": {"value": "A new item"},
#     "Attributes": [
#         {
#             "AttributeID": {"value": "COLOR"},
#             "Value": {"value": "Green"}
#         }
#     ]
# }

6. Complete Example with StockItemsService

Here is a complete example of how to use the StockItemBuilder to create a new stock item.

from easy_acumatica.models.stock_item_builder import StockItemBuilder

# 1. Build the stock item payload
item_to_create = (
    StockItemBuilder()
    .inventory_id("WIDGET-01")
    .description("Standard Widget")
    .item_class("STD")
    .set("ItemStatus", "Active")
    .add_attribute("FINISH", "Matte")
)

# 2. Use the payload with the StockItemsService to create the record
try:
    new_item = client.stock_items.create_stock_item(
        "24.200.001",
        builder=item_to_create
    )
    print(f"Successfully created stock item: {new_item['InventoryID']['value']}")
except Exception as e:
    print(f"Failed to create stock item: {e}")