Creating Shipments in Acumatica via API

The Acumatica contract-based REST API provides powerful capabilities for programmatically creating and managing shipments. Whether you're fulfilling orders from an e-commerce platform, processing returns, or automating warehouse operations, the API enables seamless shipment creation with full control over line items, allocations, and packaging.

Understanding the Shipment Entity

The Shipment entity is the primary endpoint for creating and managing shipments via the Acumatica REST API. You can create a shipment for multiple sales orders in a single API call, making it efficient for batch fulfillment scenarios.

The key components of a Shipment entity include:

• Shipment Header: Customer ID, Warehouse ID, Shipment Date, Type
• Details: Order references, Inventory IDs, Quantities, UOM
• Allocations: Lot/serial allocations for tracked inventory
• Packages: Package type, weight, dimensions

Basic Shipment Creation

To create a shipment, send a PUT request to the Shipment endpoint. The request can include details from one or more sales orders.

Request Example

PUT /entity/Default/25.200.001/Shipment?$select=Type,ShipmentNbr,Status,Details/InventoryID&$expand=Details HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "Type": { "value": "Shipment" },
    "CustomerID": { "value": "C000000003" },
    "WarehouseID": { "value": "MAIN" },
    "ShipmentDate": { "value": "2026-09-15" },
    "Details": [
        {
            "OrderType": { "value": "SO" },
            "OrderNbr": { "value": "000004" }
        },
        {
            "OrderType": { "value": "SO" },
            "OrderNbr": { "value": "000006" }
        }
    ]
}

Creating Shipments with Allocations

For inventory items that use lot or serial tracking, you can specify allocations directly in the shipment creation request. This is essential for tracking specific serial numbers or lot numbers during fulfillment.

Request Example with Allocations

PUT /entity/Default/25.200.001/Shipment?$expand=Details,Details/Allocations,Packages,Packages/PackageContents HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "CustomerID": { "value": "GOODFOOD" },
    "Details": [
        {
            "OrderNbr": { "value": "000071" },
            "OrderType": { "value": "SO" },
            "LineNbr": { "value": 1 },
            "InventoryID": { "value": "APJAM08" },
            "LocationID": { "value": "L2R3S1" },
            "UOM": { "value": "PIECE" },
            "Allocations": [
                {
                    "InventoryID": { "value": "APJAM08" },
                    "LotSerialNbr": { "value": "116046" },
                    "Qty": { "value": 1 }
                }
            ]
        },
        {
            "OrderNbr": { "value": "000072" },
            "OrderType": { "value": "SO" },
            "InventoryID": { "value": "APJAM32" },
            "LocationID": { "value": "L1R3S2" },
            "UOM": { "value": "BOX" }
        }
    ],
    "Packages": [
        {
            "PackageType": { "value": "LARGE" },
            "Weight": { "value": 15 },
            "UOM": { "value": "KG" }
        }
    ]
}

Creating Shipments with Specific Items

If you need to include particular items (rather than all items) from a sales order, you can retrieve the sales orders with the included items using the key fields, and then include the needed items by specifying the inventory ID, warehouse ID, and order details in the shipment's details.

Request Example for Partial Shipment

PUT /entity/Default/25.200.001/Shipment?$expand=Details HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "CustomerID": { "value": "GOODFOOD" },
    "WarehouseID": { "value": "MAIN" },
    "ShipmentDate": { "value": "2026-09-15" },
    "Details": [
        {
            "OrderType": { "value": "SO" },
            "OrderNbr": { "value": "000071" },
            "LineNbr": { "value": 1 },
            "InventoryID": { "value": "APJAM08" },
            "Qty": { "value": 2 }
        }
    ]
}

Managing Shipment Lifecycle

Confirming a Shipment

After creating a shipment, you can confirm it using the ConfirmShipment action. A shipment must have the Open status to be confirmed.

POST /entity/Default/25.200.001/SalesOrder/ConfirmShipment HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "entity": {
        "ShipmentNbr": { "value": "000029" }
    }
}

Preparing an Invoice from a Shipment

You can prepare a sales invoice directly from a confirmed shipment using the PrepareInvoice action. If the shipment is outgoing, the system generates a sales invoice of the Invoice type. If it's a return (incoming shipment), it generates a Credit Memo.

POST /entity/Default/25.200.001/Shipment/PrepareInvoice HTTP/1.1
Host: https://my.acumatica.com/MyInstance
Accept: application/json
Content-Type: application/json

{
    "entity": {
        "ShipmentNbr": { "value": "000067" }
    }
}

Retrieving Item Information

When working with shipments, you may need to retrieve detailed item information. The API provides two endpoints for this purpose:

• StockItem – for finished goods, component parts, and subassemblies
• NonStockItem – for services, labor, charges, and expenses

Performance Best Practices

Common API Endpoints Summary

Conclusion

The Acumatica contract-based REST API provides flexible, powerful capabilities for creating and managing shipments programmatically. Whether you're building a fulfillment system, processing returns, or automating warehouse operations, the API supports:

• Creating shipments for multiple sales orders in a single API call
• Specifying allocations for lot/serial tracked items
• Packaging specifications for shipments
• Confirming shipments and preparing invoices
• Partial shipments with specific items