Inbound Shipments API (ASN)

The Inbound Shipments API, also known as ASN (Advance Ship Notice), manages incoming inventory shipments to MasonHub distribution centers. This system allows you to notify MasonHub about expected deliveries, track receiving status, and maintain accurate inventory projections.

Creating inbound shipments automatically updates expected inventory levels and triggers real-time inventory change notifications.

Core Operations

Get Inbound Shipments

Retrieve inbound shipment information with flexible filtering options.

array

MasonHub UUIDs (1-30 items)

cid

array

Customer identifiers (1-30 items)

cpid

array

Customer purchase order IDs

status

string

Filter by shipment status (open, onDock, receivingStarted, receivingComplete)

sdt

string

Start date/time (RFC3339 format)

edt

string

End date/time (RFC3339 format)

offset

integer

default:

"0"

Pagination offset

limit

integer

default:

"30"

Number of results (1-100)

list_type

string

default:

"detail"

Response format: “detail” or “summary”

Query Parameters

Parameter	Type	Description	Default
`id`	array of UUIDs	MasonHub UUIDs [1..30]	-
`cid`	array of strings	Customer identifiers [1..30]	-
`cpid`	array of strings	Customer purchase order IDs	-
`status`	string	Filter by shipment status	-
`sdt`	string	Start date/time (RFC3339)	-
`edt`	string	End date/time (RFC3339)	-
`offset`	integer	Pagination offset	0
`limit`	integer	Number of results [1..100]	30
`list_type`	string	`detail` or `summary`	`detail`

Create Inbound Shipments

Create advance ship notices for incoming inventory shipments.

customer_identifier

string

required

Unique shipment identifier

customer_purchase_order_id

string

required

Purchase order identifier

inventory_location_id

string

required

Target warehouse location UUID

expected_arrival_date

string

required

Expected delivery date (RFC3339)

shipper_name

string

required

Name of shipping company/supplier

line_items

array

required

Array of SKUs and quantities being shipped

carrier_information

object

Detailed carrier and logistics information

tracking_number

string

Shipment tracking number

special_instructions

string

Special handling instructions

Required Fields

Shipment Identity

customer_identifier
customer_purchase_order_id
inventory_location_id

Logistics Information

expected_arrival_date
shipper_name
line_items array

Optional Details

carrier_information
tracking_number
special_instructions

Geographic Data

shipper_city
shipper_locale
shipper_country

Update Inbound Shipments

Only shipments in ‘open’ status can be updated. Updates require full object replacement.

customer_identifier

string

required

Unique shipment identifier to update

expected_arrival_date

string

Updated expected delivery date (RFC3339)

Delete Inbound Shipments

Remove inbound shipments that are no longer needed.

customer_identifier

string

required

Unique shipment identifier to delete

Shipment Status Lifecycle

open

Created and Awaiting Arrival

Shipment created, expected inventory updated, can be modified or canceled

onDock

Arrived at Facility

Physical shipment received at dock, ready for processing

receivingStarted

Processing Started

Warehouse team has begun receiving and inspecting items

receivingComplete

Fully Processed

All items received and added to available inventory

Carrier Configuration

Carrier Information Object

{
  "name": "Frankie's Red Hot Carrier",
  "type": "TL",
  "contact_name": "John Jacob",
  "driver_name": "Donny James Jr",
  "driver_phone": "555-343-4213",
  "equipment_type": "53' Dry Van",
  "appointment_required": true
}

Line Item Management

Basic Line Items

{
  "line_items": [
    {
      "customer_sku_id": "10000",
      "quantity": 80
    },
    {
      "customer_sku_id": "10001",
      "quantity": 20
    }
  ]
}

Advanced Line Items

{
  "line_items": [
    {
      "customer_sku_id": "10000",
      "quantity": 80,
      "lot_number": "LOT001",
      "expiration_date": "2025-12-31",
      "unit_cost": 25.50,
      "quality_requirements": "temperature_controlled",
      "handling_instructions": "fragile_items"
    }
  ]
}

Receiving Events & Callbacks

Inbound Shipment Events

Receive inboundShipmentEvent callbacks for status changes:

Inventory Impact

Advanced Features

Quality Control Integration

Inspection Requirements

Configure automatic quality control holds for specific SKUs or shipments

Damage Tracking

Automatically track and report damaged items during receiving

Lot Management

Support lot numbers and expiration dates for traceability

Temperature Control

Handle temperature-sensitive products with special receiving protocols

Exception Handling

Over Receipts: More items received than expected

Short Receipts: Fewer items received than expected

Damaged Items: Items received but not sellable

Wrong Items: Items not on original shipment

Best Practices

Location Validation

Always verify inventory location UUIDs before creating shipments using the inventory locations endpoint

SKU Verification

Ensure all line item SKUs exist in your catalog before creating shipments to avoid errors

Status Monitoring

Use callbacks to monitor receiving progress rather than frequent polling for better performance

Batch Operations

Process multiple shipments in single requests (up to 10) for better efficiency

Timing Considerations

Lead Time Planning: Create ASNs with sufficient lead time for warehouse planning
Appointment Scheduling: Coordinate with MasonHub for dock appointments when required
Receiving Windows: Consider warehouse operating hours for expected arrival dates
Holiday Planning: Account for warehouse closures and reduced capacity

Error Handling

Common scenarios and solutions:

Integration Patterns

ERP Integration

// Create inbound shipment from purchase order
async function createInboundFromPO(purchaseOrder) {
  const shipment = {
    customer_identifier: `shipment-${purchaseOrder.id}`,
    customer_purchase_order_id: purchaseOrder.po_number,
    inventory_location_id: await getPreferredLocation(purchaseOrder.items),
    expected_arrival_date: purchaseOrder.expected_delivery,
    shipper_name: purchaseOrder.vendor.name,
    line_items: purchaseOrder.items.map(item => ({
      customer_sku_id: item.sku,
      quantity: item.quantity
    }))
  };
  
  return await createInboundShipment([shipment]);
}

Inventory Planning

// Monitor receiving progress
function handleReceivingComplete(callback) {
  const { customer_identifier, details } = callback.data;
  
  // Update inventory projections
  details.line_items.forEach(item => {
    updateInventoryProjection(
      item.customer_sku_id, 
      item.total_quantity_received
    );
  });
  
  // Handle discrepancies
  if (details.discrepancies.length > 0) {
    processReceivingDiscrepancies(details.discrepancies);
  }
}

Next Steps

After implementing inbound shipment management, explore:

Inventory Management for tracking received inventory
Order Management for fulfilling against new inventory
Catalog Management for SKU configuration

Introduction

Getting Started

Integration

Testing & Validation

Ship Method Configuration

Getting data back into the ERP / Source System

International Shipping

Production

API Reference

Support

​Inbound Shipments API (ASN)

​Core Operations

​Get Inbound Shipments

​Query Parameters

​Create Inbound Shipments

​Required Fields

Shipment Identity

Logistics Information

Optional Details

Geographic Data

​Update Inbound Shipments

​Delete Inbound Shipments

​Shipment Status Lifecycle

​Carrier Configuration

​Carrier Information Object

​Line Item Management

​Basic Line Items

​Advanced Line Items

​Receiving Events & Callbacks

​Inbound Shipment Events

​Inventory Impact

​Advanced Features

​Quality Control Integration

Inspection Requirements

Damage Tracking

Lot Management

Temperature Control

​Exception Handling

​Best Practices

Location Validation

SKU Verification

Status Monitoring

Batch Operations

​Timing Considerations

​Error Handling

​Integration Patterns

​ERP Integration

​Inventory Planning

​Next Steps

Inbound Shipments API (ASN)

Core Operations

Get Inbound Shipments

Query Parameters

Create Inbound Shipments

Required Fields

Update Inbound Shipments

Delete Inbound Shipments

Shipment Status Lifecycle

Carrier Configuration

Carrier Information Object

Line Item Management

Basic Line Items

Advanced Line Items

Receiving Events & Callbacks

Inbound Shipment Events

Inventory Impact

Advanced Features

Quality Control Integration

Exception Handling

Best Practices

Timing Considerations

Error Handling

Integration Patterns

ERP Integration

Inventory Planning

Next Steps