MasonHub ERP Integration home pagelight logo
  1. Orders
  2. Update Orders
POST
/order_update_requests
curl --request POST \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_update_requests \
     --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": []
}'

Update existing orders asynchronously by submitting complete order objects. The system performs full replacement of order data and processes updates in the background.

Full Replacement: You must send the complete order object in each update request. The system replaces all order data with what you provide. We use POST instead of PATCH to keep integrations simple.

​
Request Body

The request body accepts an array of complete order objects with the same schema as the Create Orders endpoint.

​
Required Fields

All fields from order creation are supported. The customer_identifier is used to locate the existing order to update.

customer_identifier
required
string

Your unique order identifier. Used to locate the existing order.

order_type
required
string

Order type classification.

shipping_provider
required
string

Shipping carrier name.

shipper_service_level
required
string

Carrier service level.

submitted_at
required
string

Original order submission timestamp (RFC3339).

line_items
required
array

Complete array of line items (replaces existing items).

​
Address Fields (Required)

Include complete shipping and billing address objects with all required fields as specified in Create Orders.

curl -X POST "https://app.masonhub.co/{account}/api/v1/order_update_requests" \
  -H "Authorization: Bearer your_jwt_token" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "customer_identifier": "129374",
      "order_type": "customer",
      "priority": 150,
      "shipping_provider": "masonhub",
      "shipper_service_level": "express",
      "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": 3
        }
      ]
    }
  ]'

{
  "records_submitted": 1,
  "records_processed": 1,
  "records_failed": 0,
  "records_succeeded": 1,
  "results": [
    {
      "system_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
      "customer_identifier": "129374",
      "status": "success"
    }
  ]
}

​
Update Process

1

Fetch Current Order

Retrieve the complete current order data using GET /orders?cid=your_order_id

2

Modify Locally

Update only the fields you want to change in your local copy

3

Submit Complete Object

Send the entire modified order object to this endpoint

4

Monitor Status

Use the returned system_id to check update status via Get Order Updates

​
Asynchronous Processing

Updates are processed asynchronously in the background. Monitor completion using:

  • Polling

  • Webhooks (Recommended)

Poll the Get Order Updates endpoint with the system_id:

GET /order_update_requests?id=0b744e29-b668-4486-85dd-82528b5da0dd

Check every 30-60 seconds until status is success or failed.

​
Update Limitations

Orders cannot be updated once they reach certain fulfillment stages. Updates will be rejected with a 409 error.

Updates may fail if:

  • Order is already packed or shipped
  • Order has been canceled
  • Referenced SKUs don’t exist in catalog
  • Invalid address information
  • Update violates business rules

​
Common Update Scenarios

​
Best Practices

Update Early

Submit updates as soon as possible. Once orders enter packing, updates are no longer possible.

Fetch Before Update

Always fetch current order data first to ensure you’re working with the latest information.

Use Webhooks

Configure callbacks instead of polling for better efficiency and real-time notifications.

Handle Failures

Check error messages for failed updates and retry with corrections if needed.

Store the system_id returned when submitting updates. You’ll need it to track update status.