MasonHub ERP Integration home pagelight logo
  1. Orders
  2. Get Orders
GET
/orders
curl --request GET \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/orders \
     --header 'Authorization: Bearer <token>'

Retrieve orders from the MasonHub fulfillment system. This endpoint supports both detailed and summary views, with flexible filtering options for efficient data retrieval.

Orders are returned in descending order by creation date. Use pagination parameters for large result sets.

​
Query Parameters

Configure your request with these query parameters:

​
Primary Filters

cid
string

Filter by customer identifier. Returns specific order by your reference ID.

id
string

Filter by MasonHub system ID (UUID). Use for precise order retrieval.

list_type
default:summary
string

Response detail level:

  • summary - Basic order information (default)
  • detail - Complete order data including all fields
limit
default:100
integer

Maximum number of records to return (1-1000).

offset
default:0
integer

Number of records to skip for pagination.

​
Date Filters

created_after
string

Filter orders created after this timestamp (RFC3339 format).

created_before
string

Filter orders created before this timestamp (RFC3339 format).

updated_after
string

Filter orders updated after this timestamp (RFC3339 format).

updated_before
string

Filter orders updated before this timestamp (RFC3339 format).

​
Status Filters

status
string

Filter by order status. Options:

  • pending - Awaiting processing
  • processing - Being picked/packed
  • fulfilled - Shipped
  • delivered - Confirmed delivery
  • canceled - Order canceled
  • on_hold - Temporarily paused
has_shipments
boolean

Filter orders by shipment existence:

  • true - Only orders with shipments
  • false - Only orders without shipments
# Get specific order by customer ID
curl -X GET "https://app.masonhub.co/{account}/api/v1/orders?cid=129374" \
  -H "Authorization: Bearer your_jwt_token"

# Get detailed view of recent orders
curl -X GET "https://app.masonhub.co/{account}/api/v1/orders?list_type=detail&limit=50" \
  -H "Authorization: Bearer your_jwt_token"

# Get orders created in date range
curl -X GET "https://app.masonhub.co/{account}/api/v1/orders?created_after=2024-01-01T00:00:00Z&created_before=2024-01-31T23:59:59Z" \
  -H "Authorization: Bearer your_jwt_token"

{
  "total_count": 234,
  "limit": 100,
  "offset": 0,
  "orders": [
    {
      "system_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_identifier": "129374",
      "status": "fulfilled",
      "order_type": "customer",
      "priority": 100,
      "submitted_at": "2024-01-15T10:00:00Z",
      "created_at": "2024-01-15T10:00:15Z",
      "updated_at": "2024-01-16T14:30:00Z",
      "line_items_count": 2,
      "total_quantity": 5,
      "has_shipments": true
    },
    {
      "system_id": "660f9500-f39c-52e5-b827-557766551111",
      "customer_identifier": "129375",
      "status": "processing",
      "order_type": "customer",
      "priority": 50,
      "submitted_at": "2024-01-15T11:00:00Z",
      "created_at": "2024-01-15T11:00:10Z",
      "updated_at": "2024-01-15T11:00:10Z",
      "line_items_count": 1,
      "total_quantity": 2,
      "has_shipments": false
    }
  ]
}

​
Response Formats

​
Summary View

The default summary response includes essential order information:

system_id
string

MasonHub’s unique order identifier (UUID)

customer_identifier
string

Your order reference ID

status
string

Current order status

order_type
string

Order classification

priority
integer

Order priority level (1-999)

submitted_at
string

Original submission timestamp

line_items_count
integer

Number of distinct SKUs

total_quantity
integer

Total units across all line items

has_shipments
boolean

Whether order has been shipped

​
Detail View

The detail response includes all summary fields plus:

line_items
array

Complete line item details with quantities and allocation status

shipments
array

Shipment information including tracking details

shipping_address_*
object

Complete shipping address fields

billing_address_*
object

Complete billing address fields

value_added_services
array

Additional services requested

special_instructions
string

Warehouse handling instructions

​
Pagination

Handle large result sets using pagination:

1

Initial Request

Start with offset=0 and your desired limit (max 1000)

2

Check Total Count

Response includes total_count field showing total matching orders

3

Next Page

Increment offset by limit value for next page

4

Continue

Repeat until offset + limit >= total_count

Example pagination flow:

def get_all_orders(headers):
    all_orders = []
    offset = 0
    limit = 100

    while True:
        params = {"limit": limit, "offset": offset}
        response = requests.get(url, headers=headers, params=params)
        data = response.json()

        all_orders.extend(data["orders"])

        if offset + limit >= data["total_count"]:
            break

        offset += limit

    return all_orders

​
Order Status Lifecycle

Orders progress through these statuses:

1

pending

Order received and awaiting processing

2

processing

Order being picked and packed in warehouse

3

fulfilled

Order shipped with tracking information available

4

delivered

Carrier confirmed delivery to recipient

Additional statuses:

  • canceled - Order canceled before fulfillment
  • on_hold - Order temporarily paused (inventory, payment, or manual hold)
  • returned - Order returned after delivery

​
Best Practices

Use Specific Filters

Apply date ranges and status filters to reduce response size and improve performance.

Choose Right Detail Level

Use summary for lists and dashboards, detail only when full data needed.

Implement Pagination

Always paginate when retrieving multiple orders to avoid timeouts.

Cache When Possible

Orders in fulfilled or delivered status rarely change - cache these locally.

For real-time order updates, configure orderEvent callbacks instead of polling this endpoint.

​
Sources