Stock Items Sub Service - Nioron07/Easy-Acumatica GitHub Wiki

This guide covers the StockItemsService, which is your primary tool for interacting with StockItem records and their attachments through the contract-based API.

1. Understanding the Service's Purpose

The StockItemsService provides a comprehensive set of methods for managing stock items. You can use it to retrieve lists of items, fetch a single item by its ID, and create or update item records. It also includes a helper for retrieving file attachments associated with an item.

2. Importing Helpers

Before you start, import the necessary builders for creating stock item payloads and queries.

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

3. StockItemsService Methods

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

Method	Description	Key Parameters
.get_stock_items()	Retrieves a list of stock items.	api_version, options
.get_stock_item_by_id()	Retrieves a single stock item by its ID.	api_version, inventory_id
.create_stock_item()	Creates a new stock item.	api_version, builder
.update_stock_item()	Updates an existing stock item.	api_version, builder
.get_stock_item_attachments()	Retrieves the file attachments for a stock item.	api_version, inventory_id

4. Retrieving, Creating, and Updating Stock Items

get_stock_items(api_version, options)

This method retrieves a list of stock items. Use QueryOptions to filter, select, and expand the results.

Example: Get all active stock items

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

# 1. Create a filter for active items
opts = QueryOptions(
    filter=F.ItemStatus == "Active",
    select="InventoryID,Description,ItemClass,BaseUOM",
    expand="ItemClass"
)

# 2. Fetch the stock items
active_items = client.stock_items.get_stock_items("24.200.001", options=opts)
for item in active_items:
    print(f"Item: {item['InventoryID']['value']}, Class: {item['ItemClass']['ItemClassID']['value']}")

get_stock_item_by_id(api_version, inventory_id, ...)

Retrieves a single, complete stock item record by its InventoryID.

Example: Get a specific item

# The InventoryID of the item to fetch
item_id = "STK-ITEM-01"

# Fetch the item
item = client.stock_items.get_stock_item_by_id("24.200.001", item_id)
print(f"Fetched item: {item['Description']['value']}")

create_stock_item(api_version, builder, ...)

Creates a new stock item using a StockItemBuilder instance.

Example: Create a new stock item

from easy_acumatica.models.stock_item_builder import StockItemBuilder

# 1. Build the stock item payload
item_payload = (
    StockItemBuilder()
    .inventory_id("NEW-ITEM-001")
    .description("New Test Stock Item")
    .item_class("DEFAULT")
    .base_uom("EACH")
    .valuation_method("Standard")
)

# 2. Create the stock item
new_item = client.stock_items.create_stock_item("24.200.001", builder=item_payload)
print(f"Created Stock Item: {new_item['InventoryID']['value']}")

update_stock_item(api_version, builder, ...)

Updates an existing stock item. You must include the InventoryID in the builder to identify the record.

Example: Update an item's description

# 1. Build the update payload
update_payload = (
    StockItemBuilder()
    .inventory_id("NEW-ITEM-001") # The item to update
    .description("Updated Item Description")
)

# 2. Update the stock item
updated_item = client.stock_items.update_stock_item("24.200.001", builder=update_payload)

5. Working with Attachments

get_stock_item_attachments(api_version, inventory_id)

This helper method retrieves a list of all file attachments for a specific stock item.

Example: List all attachments for an item

item_id_with_files = "STK-ITEM-01"

attachments = client.stock_items.get_stock_item_attachments("24.200.001", item_id_with_files)

if attachments:
    print(f"Attachments for {item_id_with_files}:")
    for file in attachments:
        print(f" - {file['name']}")
else:
    print(f"No attachments found for {item_id_with_files}.")