MasonHub ERP Integration home pagelight logo
  1. Inbound Shipments/ASN
  2. Create Inbound Shipments
POST
/inbound_shipments
curl --request POST \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/inbound_shipments \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_identifier": "<string>",
  "customer_purchase_order_id": "<string>",
  "inventory_location_id": "<string>",
  "expected_arrival_date": "<string>",
  "shipper_name": "<string>",
  "line_items": [],
  "carrier_information": "<value>",
  "tracking_number": "<string>",
  "shipper_city": "<string>",
  "shipper_locale": "<string>",
  "shipper_country": "<string>",
  "special_instructions": "<string>",
  "comments": "<string>"
}'

Create advance ship notices (ASN) to notify MasonHub about expected inventory deliveries. This endpoint supports batch creation of up to 10 shipments per request.

When inbound shipments are created, the system automatically updates expected inventory totals and triggers skuInventoryChange callbacks.

All line item SKUs must exist in your catalog before creating a shipment. Non-existent SKUs will result in a validation error.

​
Request Body Schema

Send an array of inbound shipment objects. Maximum 10 shipments per request.

​
Required Fields

customer_identifier
required
string

Unique shipment identifier in your system. Used to reference this shipment in future operations.

customer_purchase_order_id
required
string

Your purchase order reference number for this shipment.

inventory_location_id
required
string

MasonHub location UUID where the shipment will be received.

expected_arrival_date
required
string

Expected delivery date in RFC3339 format (e.g., 2018-12-11T10:00:00Z).

shipper_name
required
string

Name of the shipping company or sender.

line_items
required
array

Array of items expected in the shipment. Each item must include:

  • customer_sku_id (string, required): Your SKU identifier
  • quantity (integer, required): Expected quantity

​
Optional Fields

carrier_information
object

Detailed carrier information object with fields:

  • name (string): Carrier company name
  • type (string): Carrier type (e.g., “TL”, “LTL”, “Parcel”)
  • contact_name (string): Primary contact name
  • driver_name (string): Driver’s name
  • driver_phone (string): Driver’s phone number
tracking_number
string

Carrier tracking number for the shipment.

shipper_city
string

City where the shipment is originating from.

shipper_locale
string

State or locale where the shipment is originating from (e.g., “MI”, “CA”).

shipper_country
string

Country code where the shipment is originating from (e.g., “US”, “CA”).

special_instructions
string

Special handling instructions for the warehouse team.

comments
string

Additional comments or notes about the shipment.

curl -X POST "https://app.masonhub.co/{account}/api/v1/inbound_shipments" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_identifier": "shipment32432",
      "customer_purchase_order_id": "po234532",
      "inventory_location_id": "bf7bb516-ce52-8950-2a8b-9008f0091d93",
      "carrier_information": {
        "name": "Frankie'\''s Red Hot Carrier",
        "type": "TL",
        "contact_name": "John Jacob",
        "driver_name": "Donny James Jr",
        "driver_phone": "555-343-4213"
      },
      "tracking_number": "356732154",
      "shipper_name": "Freddie'\''s Pirate Army",
      "shipper_city": "Kalamazoo",
      "shipper_locale": "MI",
      "shipper_country": "US",
      "expected_arrival_date": "2018-12-11T10:00:00Z",
      "special_instructions": "Fold using provided template during put away",
      "comments": "Shipments often not labeled but carrier is reliable",
      "line_items": [
        {
          "customer_sku_id": "10000",
          "quantity": 80
        },
        {
          "customer_sku_id": "10001",
          "quantity": 20
        }
      ]
    }
  ]'

{
  "success": true,
  "data": [
    {
      "id": "bf7bb516-ce52-8950-2a8b-9008f0091d93",
      "customer_identifier": "shipment32432",
      "customer_purchase_order_id": "po234532",
      "status": "open",
      "created_at": "2018-12-01T08:30:00Z"
    }
  ]
}

​
Inventory Integration

When you create an inbound shipment, MasonHub automatically:

1

Updates Expected Inventory

The expected inventory totals are increased for all line item SKUs

2

Triggers Callbacks

skuInventoryChange callbacks are sent for each affected SKU

3

Creates Audit Trail

All shipment changes are logged for tracking and reconciliation

​
Best Practices

Verify Location IDs

Always verify inventory location UUIDs before creating shipments to avoid routing errors.

Validate SKUs First

Ensure all line item SKUs exist in your catalog before creating shipments.

Batch When Possible

Create multiple shipments in a single request to reduce API calls (max 10 per request).

Include Carrier Details

Provide complete carrier information to help warehouse teams prepare for receiving.

​
Receiving Events

After creating a shipment, you’ll receive inboundShipmentEvent callbacks as the shipment progresses:

  • onDock: Shipment arrives at facility
  • receivingStarted: Receiving process begins
  • receivingComplete: All items processed (includes line item details and discrepancies)