Shipments Service

The `ShipmentsService` is your primary tool for interacting with `Shipment` records and their related actions. It allows you to manage the shipment lifecycle, from creation and updates to confirming the shipment and preparing an invoice from it.

Importing Helpers

To create and query shipments, you will need the `ShipmentBuilder` and other query helpers.


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

CRUD Methods

get_shipments(api_version, options=None)

Retrieves a list of shipments. Use `QueryOptions` to filter, select, and expand the results.


# Create a filter for confirmed shipments
opts = QueryOptions(
    filter=F.Status == "Confirmed",
    select="ShipmentNbr,CustomerID,WarehouseID,ShipmentDate"
)

# Fetch the shipments
confirmed_shipments = client.shipments.get_shipments("24.200.001", options=opts)

create_shipment(api_version, builder, ...)

Creates a new shipment using a `ShipmentBuilder` instance. This is typically used for creating shipments that are not generated directly from a sales order.


# Build the shipment payload
shipment_payload = (
    ShipmentBuilder()
    .customer_id("ABCCORP")
    .warehouse_id("MAIN")
    .add_detail(InventoryID="ITEM01", ShippedQty=10)
)

# Create the shipment
new_shipment = client.shipments.create_shipment("24.200.001", builder=shipment_payload)

update_shipment(api_version, builder, ...)

Updates an existing shipment. You must include the `ShipmentNbr` in the builder to identify the record to modify.


# Build the update payload to add a package
update_payload = (
    ShipmentBuilder()
    .shipment_nbr("SH001234") # The shipment to update
    .add_package(BoxID="LARGEBOX", Weight=25.5)
)

# Update the shipment
updated_shipment = client.shipments.update_shipment(
    "24.200.001",
    builder=update_payload
)

Executing Actions

The service also provides helpers to execute common actions on shipments.

confirm_shipment(api_version, shipment_nbr)

Triggers the `ConfirmShipment` action for a specific shipment. Note that this action is on the `SalesOrder` endpoint in Acumatica, but is wrapped here for convenience.


client.shipments.confirm_shipment(
    "24.200.001",
    shipment_nbr="SH001234"
)

prepare_invoice(api_version, shipment_nbr)

Executes the `PrepareInvoice` action, which generates an invoice from the shipment.


client.shipments.prepare_invoice(
    "24.200.001",
    shipment_nbr="SH001234"
)