Sales Order Sub Service - Nioron07/Easy-Acumatica GitHub Wiki

This page covers the SalesOrdersService, which is your primary tool for interacting with SalesOrder records and their related actions through the easy-acumatica API.

1. Understanding the Service's Purpose

The SalesOrdersService provides a comprehensive set of methods for managing the entire sales order lifecycle. You can use it to retrieve, create, and update sales orders, as well as execute specific actions like applying discounts or creating shipments.

2. Importing Helpers

Before you start, import the necessary builders for creating sales order payloads and queries.

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

3. SalesOrdersService Methods

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

Method	Description	Key Parameters
.get_sales_orders()	Retrieves a list of sales orders.	api_version, options
.create_sales_order()	Creates a new sales order.	api_version, builder
.update_sales_order()	Updates an existing sales order.	api_version, builder
.apply_discounts()	Executes the 'AutoRecalculateDiscounts' action.	api_version, order_type, order_nbr
.create_shipment()	Creates a shipment from a sales order.	api_version, order_id, shipment_date, warehouse_id

4. Retrieving, Creating, and Updating Sales Orders

get_sales_orders(api_version, options)

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

Example: Get all 'Open' sales orders

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

# 1. Create a filter for open orders
opts = QueryOptions(
    filter=F.Status == "Open",
    select="OrderType,OrderNbr,CustomerID,OrderTotal",
    expand="Customer"
)

# 2. Fetch the sales orders
open_orders = client.sales_orders.get_sales_orders("24.200.001", options=opts)
for order in open_orders:
    print(f"Order: {order['OrderNbr']['value']}, Customer: {order['CustomerID']['value']}")

create_sales_order(api_version, builder, ...)

Creates a new sales order using a SalesOrderBuilder instance.

Example: Create a new sales order

from easy_acumatica.models.sales_order_builder import SalesOrderBuilder

# 1. Build the sales order payload
order_payload = (
    SalesOrderBuilder()
    .order_type("SO")
    .customer_id("ABCCORP")
    .description("New order for project supplies")
    .add_detail(inventory_id="ITEM01", quantity=5, unit_price=100.0)
)

# 2. Create the sales order
new_order = client.sales_orders.create_sales_order("24.200.001", builder=order_payload)
print(f"Created Sales Order: {new_order['OrderNbr']['value']}")

update_sales_order(api_version, builder, ...)

Updates an existing sales order. You must include the OrderType and OrderNbr in the builder to identify the record.

Example: Add a line to an existing order

# 1. Build the update payload
update_payload = (
    SalesOrderBuilder()
    .order_type("SO")
    .order_nbr("SO005555") # The order to update
    .add_detail(inventory_id="ITEM02", quantity=2) # The new line to add
)

# 2. Update the sales order
updated_order = client.sales_orders.update_sales_order("24.200.001", builder=update_payload)

5. Executing Actions

The service provides helpers to execute common actions on sales orders.

apply_discounts(api_version, order_type, order_nbr)

Triggers the AutoRecalculateDiscounts action for a specific sales order.

client.sales_orders.apply_discounts(
    "24.200.001",
    order_type="SO",
    order_nbr="SO005555"
)
print("Discounts recalculated successfully.")

create_shipment(api_version, order_id, ...)

Executes the SalesOrderCreateShipment action. Note that this requires the id (GUID) of the sales order, not the OrderNbr.

# Assume 'new_order' is the response from a create_sales_order call
order_guid = new_order['id']
shipment_date = "2023-10-27T00:00:00"
warehouse_id = "MAIN"

client.sales_orders.create_shipment(
    "24.200.001",
    order_id=order_guid,
    shipment_date=shipment_date,
    warehouse_id=warehouse_id
)
print("Shipment creation process initiated.")