MasonHub ERP Integration home pagelight logo
  1. API Reference
  2. MasonHub API Documentation

The MasonHub REST API enables you to programmatically manage your entire supply chain operations, from catalog management to order fulfillment and everything in between.

​
Quick Links

Authentication

Get started with JWT bearer tokens

API Design

Understand our API principles

DataFactory

Test with simulation utilities

​
Core Resources

Catalog Management

SKU management, product information, and catalog operations

Inventory Management

Real-time inventory tracking, allocation, and availability

Order Management

Order creation, updates, cancellation, and lifecycle management

Returns (RMA)

Return merchandise authorization and processing

​
Fulfillment Operations

Inbound Shipments (ASN)

ASN management and receiving operations

Outbound Shipments

Outbound shipment tracking and carrier information

​
Integration & Testing

Callbacks & Events

Real-time webhooks for order and shipment events

Callback Events

Event payloads and specifications

DataFactory Testing

Testing utilities for simulating operations

​
Security & Tokens

Token Management

Generate and manage JWT bearer tokens for API authentication

​
Authentication

All API endpoints require HTTPS with a valid JWT Bearer token. Generate tokens through the Token Management endpoints.

Bearer tokens begin with the eyJ prefix and must be included in the Authorization header of all requests. Keep your bearer tokens secret.

​
Using Your Token

Include the bearer token in the Authorization header:

curl -X GET "https://app.masonhub.co/{account}/api/v1/orders" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Base URLs

  • Sandbox

  • Production

https://sandbox.masonhub.co/{account_slug}/api/v1/

Use for development and testing without affecting production data.

Replace {account_slug} with your MasonHub account identifier.

​
API Design Principles

The MasonHub API follows consistent design principles for a predictable and powerful developer experience:

Search-First Design

GET methods use search parameters for composability and flexible data retrieval. Everything is really just search.

Batch Operations

All methods accept and return arrays for efficient bulk operations. Process multiple items in single API calls.

Flexible Responses

Use list_type=detail|summary to control response detail levels and optimize data transfer.

RESTful Design

Standard GET, POST, PUT, DELETE operations. No PATCH to maintain simplicity.

Robust Error Handling

Bulk operations are non-blocking with individual success/failure status for each item.

Consistent Formatting

RFC3339 date format used throughout for consistency and international support.

​
Data Formats

​
Date and Time

All timestamps use RFC3339 format for consistency and timezone support:

{
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:45:30Z"
}

​
Pagination

Standard pagination parameters across all list endpoints:

limit
default:30
integer

Number of results to return. Range: 1-100.

offset
default:0
integer

Pagination offset for retrieving subsequent pages of results.

list_type
default:detail
string

Response detail level. Options:

  • detail - Full information including all fields
  • summary - Condensed view with essential fields only

​
Response Structure

All list responses follow a consistent structure:

{
  "limit": 30,
  "offset": 0,
  "list_type": "detail",
  "data": [
    {
      // Array of result objects
    }
  ]
}

​
Batch Operation Responses

Bulk operations return detailed status for each item:

{
  "records_submitted": 5,
  "records_processed": 5,
  "records_failed": 1,
  "records_succeeded": 4,
  "results": [
    {
      "customer_identifier": "item-001",
      "status": "success"
    },
    {
      "customer_identifier": "item-002",
      "status": "failure",
      "error_message": "SKU not found in catalog"
    }
  ]
}

​
API Resources by Category

​
Additional Resources

The Stack Trace

Understanding MasonHub’s logging and audit trail system

API Design Philosophy

Core principles behind the API design

​
Support

For API support and integration assistance:

Integration Support

Technical integration questions

General Support

General inquiries and account support

​
Getting Started

Ready to integrate with MasonHub? Follow these steps:

1

Generate API Token

Create your JWT bearer token using the Token Management endpoint

2

Test in Sandbox

Use the sandbox environment to test your integration without affecting production data

3

Create Catalog

Set up your SKUs and product catalog

4

Configure Callbacks

Set up webhooks for real-time event notifications

5

Test with DataFactory

Use DataFactory to simulate operations and validate your integration

6

Go Live

Move to production with confidence after thorough testing