MasonHub ERP Integration home pagelight logo
  1. Orders
  2. Create Orders
POST
/orders
curl --request POST \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/orders \
     --header 'Authorization: Bearer <token>' \
     --header 'Content-Type: application/json' \
     --data '{
  "customer_identifier": "<string>",
  "order_type": "<string>",
  "shipping_provider": "<string>",
  "shipper_service_level": "<string>",
  "submitted_at": "<string>",
  "line_items": [],
  "shipping_address_name": "<string>",
  "shipping_address_street_line_one": "<string>",
  "shipping_address_street_line_two": "<string>",
  "shipping_address_city": "<string>",
  "shipping_address_locale": "<string>",
  "shipping_address_postal_code": "<string>",
  "shipping_address_country_code": "<string>",
  "shipping_address_phone_number": "<string>",
  "shipping_address_type": "<string>",
  "billing_address_name": "<string>",
  "billing_address_street_line_one": "<string>",
  "billing_address_street_line_two": "<string>",
  "billing_address_city": "<string>",
  "billing_address_locale": "<string>",
  "billing_address_postal_code": "<string>",
  "billing_address_country_code": "<string>",
  "billing_address_phone_number": "<string>",
  "billing_address_type": "<string>",
  "priority": 123,
  "value_added_services": [],
  "special_instructions": "<string>",
  "gift_message": "<string>",
  "backorder_policy": "<string>",
  "routing_policy": "<string>",
  "split_policy": "<string>",
  "order_localization": "<value>",
  "sku_customer_id": "<string>",
  "quantity": 123,
  "promised_delivery_date": "<string>",
  "estimated_delivery_date": "<string>",
  "pick_from": []
}'

Create new orders in the MasonHub fulfillment system. Orders can be submitted individually or in batches, with support for complex routing policies, inventory allocation constraints, and custom shipping requirements.

Orders are processed synchronously. The API returns immediately with creation status and assigned order IDs.

​
Request Body

The request body accepts an array of order objects. Each order supports the following fields:

​
Required Fields

customer_identifier
required
string

Unique order identifier from your system. This is your primary reference for tracking the order.

order_type
required
string

Order type classification (e.g., “customer”, “replacement”, “sample”).

shipping_provider
required
string

Shipping carrier name (e.g., “masonhub”, “UPS”, “FedEx”, “USPS”).

shipper_service_level
required
string

Carrier service level. Options: ground, express, overnight, two_day.

submitted_at
required
string

Order submission timestamp in RFC3339 format (e.g., “2018-08-01T00:00:00Z”).

line_items
required
array

Array of line item objects. Each item requires sku_customer_id and quantity.

​
Shipping Address (Required)

shipping_address_name
required
string

Recipient full name.

shipping_address_street_line_one
required
string

Street address line 1.

shipping_address_street_line_two
string

Street address line 2 (apartment, suite, etc.).

shipping_address_city
required
string

City name.

shipping_address_locale
required
string

State/province code (e.g., “NJ”, “CA”).

shipping_address_postal_code
required
string

Postal/ZIP code.

shipping_address_country_code
required
string

Two-letter ISO country code (e.g., “US”, “CA”).

shipping_address_phone_number
required
string

Contact phone number.

shipping_address_type
required
string

Address type. Options: residential or commercial.

​
Billing Address (Required)

billing_address_name
required
string

Billing contact name.

billing_address_street_line_one
required
string

Billing street address line 1.

billing_address_street_line_two
string

Billing street address line 2.

billing_address_city
required
string

Billing city.

billing_address_locale
required
string

Billing state/province code.

billing_address_postal_code
required
string

Billing postal/ZIP code.

billing_address_country_code
required
string

Billing country code.

billing_address_phone_number
required
string

Billing phone number.

billing_address_type
required
string

Billing address type: residential or commercial.

​
Optional Fields

priority
integer

Order priority (higher values = more urgent). Range: 1-999.

value_added_services
array

Array of additional service strings to be performed (e.g., gift wrapping, custom packaging).

special_instructions
string

Special handling instructions for warehouse staff.

gift_message
string

Gift message to include with the order.

backorder_policy
string

How to handle out-of-stock items. Options:

  • cancel_shorts - Cancel unavailable items
  • backorder - Hold order until inventory available
  • partial_ship - Ship available items immediately
routing_policy
string

Fulfillment routing strategy for multi-warehouse scenarios.

split_policy
string

Order splitting rules. Options:

  • single_shipment - Never split orders
  • allow_splits - Allow splits for efficiency
  • minimize_splits - Prefer single shipments but allow splits
order_localization
object

Localization settings for international orders.

​
Line Items

Each line item in the line_items array supports:

sku_customer_id
required
string

Your SKU identifier (must exist in catalog).

quantity
required
integer

Quantity to ship.

promised_delivery_date
string

Promised delivery date in RFC3339 format.

estimated_delivery_date
string

Estimated delivery date in RFC3339 format.

pick_from
array

Inventory allocation constraints. Each rule specifies match_type, match_value, and match_style.

curl -X POST "https://app.masonhub.co/{account}/api/v1/orders" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_identifier": "129374",
      "order_type": "customer",
      "priority": 100,
      "shipping_provider": "masonhub",
      "shipper_service_level": "ground",
      "value_added_services": ["Complimentary Handkerchief"],
      "special_instructions": "Triple Fold the Sleeves and wrap in Tissue Paper.",
      "gift_message": "Happy Birthday Freddie!",
      "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_phone_number": "973-999-3333",
      "shipping_address_type": "residential",
      "billing_address_name": "John Jacob JingleHeimer-Schmidt III",
      "billing_address_street_line_one": "234 House Lane",
      "billing_address_city": "Little Falls",
      "billing_address_locale": "NJ",
      "billing_address_postal_code": "07972",
      "billing_address_country_code": "US",
      "billing_address_phone_number": "973-999-3333",
      "billing_address_type": "residential",
      "submitted_at": "2018-08-01T00:00:00Z",
      "line_items": [
        {
          "sku_customer_id": "shirts872340",
          "quantity": 2,
          "promised_delivery_date": "2018-08-15T17:32:28Z",
          "estimated_delivery_date": "2018-08-15T17:32:28Z"
        }
      ]
    }
  ]'

{
  "records_submitted": 1,
  "records_processed": 1,
  "records_failed": 0,
  "records_succeeded": 1,
  "results": [
    {
      "system_id": "550e8400-e29b-41d4-a716-446655440000",
      "customer_identifier": "129374",
      "status": "success"
    }
  ]
}

​
Advanced Features

​
Pick From Constraints

Control exactly which inventory is allocated to orders using pick_from rules:

  • Hard Match

  • Soft Match

Required Constraint: Order will fail if inventory doesn’t match criteria.

{
  "pick_from": [
    {
      "match_type": "purchase_order",
      "match_value": ["PO23423", "PO42322"],
      "match_style": "hard"
    }
  ]
}

Use for: Specific lot requirements, quality control, customer-specific inventory.

​
Order Splitting Policies

Configure how orders can be split across multiple shipments:

Single Shipment

Never split orders. Wait until all items are available to ship together.

Allow Splits

Allow orders to split freely for maximum efficiency and speed.

Minimize Splits

Prefer single shipments but allow splits if necessary to avoid delays.

​
Backorder Policies

Handle out-of-stock scenarios:

1

Cancel Shorts

Cancel unavailable items immediately. Customer receives partial order.

2

Backorder

Hold entire order until all items are available. Guarantees complete order.

3

Partial Ship

Ship available items immediately, backorder the rest. Balance of speed and completeness.

​
Order Events and Callbacks

Configure webhooks to receive real-time order status updates:

​
Best Practices

Always provide complete shipping and billing addresses with country codes. Missing address fields will cause validation errors.

Validate SKUs First

Ensure all line item SKUs exist in your catalog before creating orders.

Set Realistic Priorities

Use priority judiciously. Too many high-priority orders reduce effectiveness.

Use Callbacks

Configure orderEvent webhooks for real-time status updates instead of polling.

Batch Operations

Submit multiple orders in single API calls for improved performance.

Store the system_id (MasonHub order UUID) returned in the response for future order queries and updates.