Order Management API

The Orders API manages the complete order lifecycle from creation to fulfillment. It supports various order types, complex routing policies, asynchronous update operations, and real-time status tracking through callbacks.

Orders progress through statuses automatically as they move through the fulfillment process. Use callbacks for real-time updates.

Core Operations

Get Orders

Retrieve orders with filtering and pagination support.

UUID[]

MasonHub UUIDs [1..30]

offset

integer

default:

"0"

Pagination offset

limit

integer

default:

"30"

Number of results [1..100]

list_type

string

default:

"detail"

Response detail level: detail or summary

sdt

string

Start date for updated_at filter (RFC3339)

Parameter	Type	Description	Default
`id`	array of UUIDs	MasonHub UUIDs [1..30]	-
`offset`	integer	Pagination offset	0
`limit`	integer	Number of results [1..100]	30
`list_type`	string	`detail` or `summary`	`detail`
`sdt`	string	Start date for updated_at filter (RFC3339)	-

Create Orders

Create one or more orders with comprehensive configuration options.

customer_identifier

string

required

Unique order identifier

order_type

string

required

Order type (e.g., “customer”)

priority

integer

Order priority (higher = more urgent)

shipping_provider

string

required

Shipping provider name

shipper_service_level

string

required

Service level (ground, express, etc.)

shipping_address_name

string

required

Recipient’s full name

shipping_address_street_line_one

string

required

Street address line 1

shipping_address_city

string

required

City name

shipping_address_locale

string

required

State/province code

shipping_address_postal_code

string

required

ZIP/postal code

shipping_address_country_code

string

required

Country code (e.g., “US”)

submitted_at

string

required

Order submission time (RFC3339)

line_items

array

required

Array of order line items

Required Fields

Order Identification

customer_identifier
order_type
submitted_at

Shipping Configuration

shipping_provider
shipper_service_level
Complete shipping address

Billing Information

Complete billing address
Address validation fields

Order Contents

line_items array
SKU customer identifiers
Quantities

Address Schema

Both shipping and billing addresses require complete information:

{
  "shipping_address_name": "John Jacob JingleHeimer-Schmidt III",
  "shipping_address_street_line_one": "234 House Lane",
  "shipping_address_city": "Little Falls",
  "shipping_address_locale": "NJ",
  "shipping_address_postal_code": "07972",
  "shipping_address_country_code": "US",
  "shipping_address_type": "residential"
}

Update Orders

Order updates require full order objects and are processed asynchronously. Monitor callbacks for completion status.

customer_identifier

string

required

Unique order identifier to update

priority

integer

Updated order priority

order_type

string

Order type (typically unchanged)

shipping_provider

string

Updated shipping provider

line_items

array

Updated line items array

Cancel Orders

Cancel one or more orders by customer identifier or cancel request ID.

customer_identifier

string

Unique order identifier to cancel

order_cancel_request_id

string

UUID for cancel request tracking

Order Status Lifecycle

open

Order created and validated, awaiting fulfillment

atWarehouse

Order received at distribution center

inProcess

Order being picked and packed

packed

Order packed and ready to ship

fulfilled

Order shipped to customer with tracking

delivered

Order delivered to customer (via carrier update)

canceled

Order canceled (manual or system)

Advanced Configuration

Pick From Constraints

Control inventory allocation with granular pick_from rules:

Match Styles

Hard Match

Required constraint - Order fails if constraint cannot be met

Use for critical requirements like specific lot numbers

Soft Match

Preferred constraint - System attempts to match but fulfills anyway

Use for preferences like newer inventory

Order Policies

Configure how orders behave across different scenarios:

single_shipment: Never split orders across multiple shipments

allow_splits: Allow splits for operational efficiency

minimize_splits: Prefer single shipments but allow splits when necessary

{
  "split_policy": "minimize_splits"
}

Value Added Services

Enhance orders with additional services:

{
  "value_added_services": [
    "Gift Wrapping",
    "Complimentary Handkerchief", 
    "Express Processing",
    "Signature Required",
    "Insurance Coverage"
  ]
}

Event Callbacks

Order Events

Real-time order status updates via orderEvent callbacks:

Update Resolution

Monitor asynchronous operations:

orderUpdateResolution callbacks indicate success/failure of update requests.

{
  "message_type": "orderUpdateResolution",
  "data": {
    "update_request_id": "uuid-here",
    "customer_identifier": "129374",
    "status": "success",
    "updated_at": "2018-08-06T15:11:19Z"
  }
}

orderCancelResolution callbacks indicate success/failure of cancel requests.

{
  "message_type": "orderCancelResolution",
  "data": {
    "cancel_request_id": "uuid-here", 
    "customer_identifier": "129374",
    "status": "success",
    "canceled_at": "2018-08-06T15:11:19Z"
  }
}

Line Item Configuration

Basic Line Items

{
  "line_items": [
    {
      "sku_customer_id": "shirts872340",
      "quantity": 2,
      "promised_delivery_date": "2018-08-15T17:32:28Z",
      "estimated_delivery_date": "2018-08-15T17:32:28Z"
    }
  ]
}

Advanced Line Items

{
  "line_items": [
    {
      "sku_customer_id": "shirts872340",
      "quantity": 2,
      "unit_price": 25.99,
      "line_total": 51.98,
      "promised_delivery_date": "2018-08-15T17:32:28Z",
      "pick_from": [
        {
          "match_type": "purchase_order",
          "match_value": ["PO23423"],
          "match_style": "hard"
        }
      ],
      "personalization": {
        "monogram": "JJS",
        "color_preference": "navy"
      }
    }
  ]
}

Monitoring Operations

Check Update Status

GET /order_update_requests?id=uuid1,uuid2&limit=10
Authorization: Bearer your_jwt_token

Check Cancel Status

GET /order_cancel_requests?id=uuid1,uuid2&limit=10
Authorization: Bearer your_jwt_token

Best Practices

Address Validation

Always provide complete shipping and billing addresses with proper country codes

Asynchronous Monitoring

Monitor callback events for update/cancel confirmations rather than polling

SKU Validation

Ensure all line item SKUs exist and have available inventory before creating orders

Batch Processing

Process multiple orders in single requests when possible for better efficiency

Performance Tips

Use Summary Lists: Start with list_type=summary for order browsing
Date Filtering: Use sdt parameter to fetch recent updates only
Reasonable Limits: Use appropriate limit values to avoid timeouts
Callback Optimization: Process callbacks efficiently to handle high order volumes

Error Handling

Common error scenarios and solutions:

Next Steps

After setting up order management, explore:

Shipment Tracking for delivery monitoring
Inventory Management for stock levels
Callback Configuration for event handling

Introduction

Getting Started

Integration

Testing & Validation

Ship Method Configuration

Getting data back into the ERP / Source System

International Shipping

Production

API Reference

Support

​Order Management API

​Core Operations

​Get Orders

​Create Orders

​Required Fields

Order Identification

Shipping Configuration

Billing Information

Order Contents

​Address Schema

​Update Orders

​Cancel Orders

​Order Status Lifecycle

​Advanced Configuration

​Pick From Constraints

​Match Styles

Hard Match

Soft Match

​Order Policies

​Value Added Services

​Event Callbacks

​Order Events

​Update Resolution

​Line Item Configuration

​Basic Line Items

​Advanced Line Items

​Monitoring Operations

​Check Update Status

​Check Cancel Status

​Best Practices

Address Validation

Asynchronous Monitoring

SKU Validation

Batch Processing

​Performance Tips

​Error Handling

​Next Steps

Order Management API

Core Operations

Get Orders

Create Orders

Required Fields

Address Schema

Update Orders

Cancel Orders

Order Status Lifecycle

Advanced Configuration

Pick From Constraints

Match Styles

Order Policies

Value Added Services

Event Callbacks

Order Events

Update Resolution

Line Item Configuration

Basic Line Items

Advanced Line Items

Monitoring Operations

Check Update Status

Check Cancel Status

Best Practices

Performance Tips

Error Handling

Next Steps