Inventory Management - MasonHub ERP Integration

The Inventory API provides real-time inventory tracking and snapshot capabilities across all distribution centers. It supports various inventory statuses, detailed location breakdowns, and automatic inventory change notifications.

Use callbacks for real-time inventory updates rather than frequent polling to optimize performance and stay current with inventory changes.

Core Operations

Get SKU Inventory

Retrieve real-time inventory levels across all locations and statuses.

cid

array

required

Customer SKU identifiers (1-30 items)

limit

integer

default:

"30"

Number of results (1-100)

offset

integer

default:

"0"

Pagination offset

include_ledger

boolean

default:

"true"

Include detailed inventory breakdown by location

Query Parameters

Parameter	Type	Description	Default
`cid`	array of strings	Customer identifiers [1..30]	-
`limit`	integer	Number of results [1..100]	30
`offset`	integer	Pagination offset	0

Request Full Snapshot

For large datasets or bulk operations, use asynchronous snapshots:

snapshot_type

string

required

Type of snapshot: “full” or “delta”

snapshot_as_of_date

string

Point-in-time for snapshot (RFC3339)

“estimated_completion”: “2019-08-05T08:20:30-07:00” }

</CodeGroup>

<Warning>
Full snapshots are processed asynchronously. Monitor for **SnapshotReady** callbacks containing download links.
</Warning>

### Get Inventory Locations

```http
GET /{accountSlug}/inventory_locations
Authorization: Bearer your_jwt_token

Inventory Status Types

Sellable Inventory

available: Ready for sale and allocation

expected: Incoming from inbound shipments

received: Recently received, being processed

Quality Control

quality-control: Under inspection

refurbishing: Being repaired/refurbished

under-investigation: Status being determined

Processing States

in-receiving: Currently being processed

allocated: Reserved for orders

picked: Retrieved for shipment

Unavailable

damaged: Requires disposition

lost: Cannot be located

expired: Past expiration date

Inventory Calculations

Total Available to Sell

The key metric for order allocation:

Available to Sell = Available + Expected + Received

Includes inventory ready for immediate allocation plus incoming stock that can be promised to orders.

Multi-Location Aggregation

Location-Level Counts

Inventory tracked separately by distribution center

Status Aggregation

Each location provides status-specific breakdowns

Total Calculation

System aggregates across all locations for total counts

Available Calculation

Only sellable statuses contribute to available-to-sell

Real-time Updates

Inventory Change Callbacks

Receive skuInventoryChange callbacks for real-time updates:

Snapshot Ready Callbacks

Receive SnapshotReady callbacks when full snapshots complete:

{
  "callback_url": "https://client.com/api/snapshot_ready",
  "message_type": "SnapshotReady",
  "message_id": "f68870ed-d5dc-48g0-c81b-489b0c96bfbf",
  "data": {
    "snapshot_request_id": "550e8400-e29b-41d4-a716-446655440000",
    "snapshot_type": "full",
    "snapshot_as_of_date": "2019-08-05T08:15:30-07:00",
    "download_url": "https://secure.masonhub.com/snapshots/download/abc123",
    "expires_at": "2019-08-05T20:15:30-07:00",
    "record_count": 15420
  }
}

Advanced Features

Kit Inventory Tracking

Characteristics:

Tracked as single inventory units
Components unavailable individually
Fast pick and ship processing

Inventory Display:

{
  "customer_identifier": "kit-001",
  "total_units": 50,
  "total_available_to_sell": 50,
  "kit_type": "pre-built"
}

Characteristics:

Components tracked individually
Available quantity based on limiting component
Flexible inventory allocation

Inventory Display:

{
  "customer_identifier": "kit-002",
  "total_units": 25,
  "total_available_to_sell": 20,
  "kit_type": "kit-to-ship",
  "limiting_component": "component-b"
}

Location-Specific Operations

Multi-DC Distribution

Inventory automatically distributed across multiple distribution centers based on:

Geographic optimization
Capacity constraints
Customer proximity

Location-Specific Queries

Filter inventory by specific locations:

GET /inventory?cid=sku001&location_id=uuid

Inventory Adjustments

Track all inventory movements with detailed audit trails:

{
  "adjustment_reason": "cycle_count_adjustment",
  "previous_quantity": 100,
  "new_quantity": 95,
  "adjustment_quantity": -5,
  "adjusted_by": "warehouse_user_123",
  "adjustment_notes": "Physical count variance"
}

Best Practices

Real-time Updates

Use callbacks for inventory changes rather than frequent polling to reduce API load and get immediate updates

Batch Queries

Query multiple SKUs in single requests (up to 30) for better performance and reduced rate limiting

Snapshot Strategy

Use full snapshots for:

Initial system synchronization
End-of-day reporting
Bulk reconciliation processes

Status Understanding

Understand which statuses contribute to available-to-sell calculations for accurate order promising

Performance Optimization

Callback Processing: Design callback handlers to process inventory updates quickly
Status Filtering: Focus on sellable statuses for order management systems
Location Awareness: Consider location-specific inventory for regional fulfillment
Kit Complexity: Account for kit component dependencies in availability calculations

Error Handling

Common scenarios and solutions:

Integration Patterns

E-commerce Integration

// Real-time inventory sync
function handleInventoryChange(callback) {
  const { sku_id, customer_identifier, total_available_to_sell } = callback.data[0];
  
  // Update product availability
  updateProductAvailability(customer_identifier, total_available_to_sell);
  
  // Trigger out-of-stock notifications if needed
  if (total_available_to_sell === 0) {
    notifyOutOfStock(customer_identifier);
  }
}

ERP Synchronization

// Daily inventory reconciliation
async function dailyInventorySync() {
  // Request full snapshot
  const snapshot = await requestFullSnapshot();
  
  // Process when ready
  const inventoryData = await downloadSnapshot(snapshot.download_url);
  
  // Reconcile with ERP system
  await reconcileWithERP(inventoryData);
}

Next Steps

After implementing inventory management, explore:

Inbound Shipments for receiving inventory
Order Management for allocation and fulfillment
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

​Core Operations

​Get SKU Inventory

​Query Parameters

​Request Full Snapshot

​Inventory Status Types

Sellable Inventory

Quality Control

Processing States

Unavailable

​Inventory Calculations

​Total Available to Sell

​Multi-Location Aggregation

​Real-time Updates

​Inventory Change Callbacks

​Snapshot Ready Callbacks

​Advanced Features

​Kit Inventory Tracking

​Location-Specific Operations

Multi-DC Distribution

Location-Specific Queries

​Inventory Adjustments

​Best Practices

Real-time Updates

Batch Queries

Snapshot Strategy

Status Understanding

​Performance Optimization

​Error Handling

​Integration Patterns

​E-commerce Integration

​ERP Synchronization

​Next Steps

Core Operations

Get SKU Inventory

Query Parameters

Request Full Snapshot

Inventory Status Types

Inventory Calculations

Total Available to Sell

Multi-Location Aggregation

Real-time Updates

Inventory Change Callbacks

Snapshot Ready Callbacks

Advanced Features

Kit Inventory Tracking

Location-Specific Operations

Inventory Adjustments

Best Practices

Performance Optimization

Error Handling

Integration Patterns

E-commerce Integration

ERP Synchronization

Next Steps