Get Order Updates - MasonHub ERP Integration

Orders
Get Order Updates

GET

/order_update_requests

curl --request GET \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_update_requests \
     --header 'Authorization: Bearer <token>'

Retrieve the status and details of previously submitted order update requests. Use this endpoint to monitor the asynchronous processing of order modifications and verify successful updates.

Order update requests are processed asynchronously. Poll this endpoint or configure webhooks to track completion status.

Query Parameters

Filter and retrieve update requests with these parameters:

string

Filter by update request system ID (UUID). Returns specific update request.

cid

string

Filter by customer identifier. Returns all update requests for a specific order.

status

string

Filter by request status:

pending - Awaiting processing
processing - Currently being processed
success - Update completed successfully
failed - Update failed with errors
partial - Some updates applied, others failed

limit

default:100

integer

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

offset

default:0

integer

Number of records to skip for pagination.

created_after

string

Filter requests created after this timestamp (RFC3339 format).

created_before

string

Filter requests created before this timestamp (RFC3339 format).

resolved_after

string

Filter requests resolved after this timestamp (RFC3339 format).

resolved_before

string

Filter requests resolved before this timestamp (RFC3339 format).

# Get specific update request by ID
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?id=0b744e29-b668-4486-85dd-82528b5da0dd" \
  -H "Authorization: Bearer your_jwt_token"

# Get all update requests for an order
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?cid=129374" \
  -H "Authorization: Bearer your_jwt_token"

# Get pending update requests
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?status=pending&limit=50" \
  -H "Authorization: Bearer your_jwt_token"

{
  "total_count": 3,
  "limit": 100,
  "offset": 0,
  "update_requests": [
    {
      "system_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
      "customer_identifier": "129374",
      "status": "success",
      "submitted_at": "2024-01-17T10:00:00Z",
      "resolved_at": "2024-01-17T10:00:45Z",
      "updates_applied": {
        "shipper_service_level": {
          "old": "ground",
          "new": "express"
        },
        "priority": {
          "old": 100,
          "new": 150
        }
      },
      "processing_time_ms": 450,
      "order_status": "processing"
    },
    {
      "system_id": "1c855f30-c779-5597-96ee-93639c6eb1ee",
      "customer_identifier": "129374",
      "status": "failed",
      "submitted_at": "2024-01-16T15:30:00Z",
      "resolved_at": "2024-01-16T15:30:05Z",
      "error": {
        "code": "ORDER_LOCKED",
        "message": "Cannot update order in fulfilled status",
        "details": {
          "order_status": "fulfilled",
          "shipped_at": "2024-01-16T14:00:00Z"
        }
      },
      "processing_time_ms": 50
    },
    {
      "system_id": "2d966g41-d88a-6608-a7ff-a4740d7fc2ff",
      "customer_identifier": "129374",
      "status": "pending",
      "submitted_at": "2024-01-17T11:00:00Z",
      "submitted_changes": {
        "line_items": [
          {
            "sku_customer_id": "shirts872340",
            "quantity": 5
          }
        ]
      }
    }
  ]
}

Response Fields

system_id

string

Unique identifier for the update request

customer_identifier

string

Your order reference ID

status

string

Current status of the update request:

pending - Queued for processing
processing - Currently being applied
success - All updates applied successfully
failed - Updates could not be applied
partial - Some updates applied, others failed

submitted_at

string

Timestamp when update request was submitted

resolved_at

string

Timestamp when processing completed (null if pending)

updates_applied

object

Details of successfully applied changes with old/new values

updates_failed

object

Details of failed updates with error reasons

error

object

Error details if entire request failed

processing_time_ms

integer

Time taken to process the request in milliseconds

order_status

string

Current status of the order after update

Update Request Lifecycle

pending

Request received and queued for processing

processing

System actively applying updates to the order

Resolution

Final status determined:

success - All changes applied
failed - No changes applied
partial - Some changes applied

Polling Strategy

Implement efficient polling to monitor update status:

import time
import requests

def wait_for_update_completion(update_id, headers, timeout=300):
    """
    Poll for update completion with exponential backoff
    """
    url = f"https://app.masonhub.co/{{account}}/api/v1/order_update_requests"
    start_time = time.time()
    poll_interval = 5  # Start with 5 seconds

    while time.time() - start_time < timeout:
        response = requests.get(
            url,
            headers=headers,
            params={"id": update_id}
        )

        data = response.json()
        if data["update_requests"]:
            status = data["update_requests"][0]["status"]

            if status in ["success", "failed", "partial"]:
                return data["update_requests"][0]

        time.sleep(poll_interval)
        # Exponential backoff with max 60 seconds
        poll_interval = min(poll_interval * 1.5, 60)

    raise TimeoutError(f"Update {update_id} did not complete within {timeout} seconds")

Common Update Scenarios

Track different types of order modifications:

Address Change
Service Level Change
Quantity Change

Monitor shipping address updates:

{
  "updates_applied": {
    "shipping_address_street_line_one": {
      "old": "123 Main St",
      "new": "456 Park Ave"
    },
    "shipping_address_city": {
      "old": "Old City",
      "new": "New City"
    }
  }
}

Error Types

Common error codes and their meanings:

Not enough stock available for requested quantity increase

{
  "code": "INSUFFICIENT_INVENTORY",
  "message": "Cannot increase quantity - only 3 units available",
  "available_quantity": 3,
  "requested_quantity": 10
}

Best Practices

Use Webhooks

Configure orderUpdateResolution callbacks instead of polling

Implement Backoff

Use exponential backoff when polling to reduce API load

Handle Partials

Check both updates_applied and updates_failed for partial successes

Track Request IDs

Store system_id from submission for reliable status tracking

Update requests older than 30 days may be archived and unavailable through this endpoint. Store important update history in your own system.

Webhook Alternative

For real-time updates without polling, configure webhooks:

POST /callbacks
{
  "callback_url": "https://your-api.com/webhooks/order-updates",
  "event_type": "orderUpdateResolution"
}

You’ll receive notifications when update requests complete:

{
  "message_type": "orderUpdateResolution",
  "data": [
    {
      "update_request_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
      "customer_identifier": "129374",
      "status": "success",
      "resolved_at": "2024-01-17T10:00:45Z"
    }
  ]
}

For high-volume operations, use webhooks instead of polling. This reduces API calls and provides faster notification of update completions.

Update Orders - Submit order update requests
Get Orders - Retrieve current order data
Order Update Resolutions - Webhook configuration

Sources

# Get specific update request by ID
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?id=0b744e29-b668-4486-85dd-82528b5da0dd" \
  -H "Authorization: Bearer your_jwt_token"

# Get all update requests for an order
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?cid=129374" \
  -H "Authorization: Bearer your_jwt_token"

# Get pending update requests
curl -X GET "https://app.masonhub.co/{account}/api/v1/order_update_requests?status=pending&limit=50" \
  -H "Authorization: Bearer your_jwt_token"

curl --request GET \
     --url https://sandbox.masonhub.co/dragonfly-cosmetics-demo/api/v1/order_update_requests \
     --header 'Authorization: Bearer <token>'

{
  "total_count": 3,
  "limit": 100,
  "offset": 0,
  "update_requests": [
    {
      "system_id": "0b744e29-b668-4486-85dd-82528b5da0dd",
      "customer_identifier": "129374",
      "status": "success",
      "submitted_at": "2024-01-17T10:00:00Z",
      "resolved_at": "2024-01-17T10:00:45Z",
      "updates_applied": {
        "shipper_service_level": {
          "old": "ground",
          "new": "express"
        },
        "priority": {
          "old": 100,
          "new": 150
        }
      },
      "processing_time_ms": 450,
      "order_status": "processing"
    },
    {
      "system_id": "1c855f30-c779-5597-96ee-93639c6eb1ee",
      "customer_identifier": "129374",
      "status": "failed",
      "submitted_at": "2024-01-16T15:30:00Z",
      "resolved_at": "2024-01-16T15:30:05Z",
      "error": {
        "code": "ORDER_LOCKED",
        "message": "Cannot update order in fulfilled status",
        "details": {
          "order_status": "fulfilled",
          "shipped_at": "2024-01-16T14:00:00Z"
        }
      },
      "processing_time_ms": 50
    },
    {
      "system_id": "2d966g41-d88a-6608-a7ff-a4740d7fc2ff",
      "customer_identifier": "129374",
      "status": "pending",
      "submitted_at": "2024-01-17T11:00:00Z",
      "submitted_changes": {
        "line_items": [
          {
            "sku_customer_id": "shirts872340",
            "quantity": 5
          }
        ]
      }
    }
  ]
}

​Query Parameters

​Response Fields

​Update Request Lifecycle

pending

processing

Resolution

​Polling Strategy

​Common Update Scenarios

Address Change

Service Level Change

Quantity Change

​Error Types

​Best Practices

Use Webhooks

Implement Backoff

Handle Partials

Track Request IDs

​Webhook Alternative

​Related Endpoints

​Sources

Query Parameters

Response Fields

Update Request Lifecycle

Polling Strategy

Common Update Scenarios

Error Types

Best Practices

Webhook Alternative

Related Endpoints

Sources