POST

Send Notification

Forcibly send customer notifications (email, SMS, WhatsApp) for a specific order.

Endpoint

HTTP Request

POST /v1/orders/:order_id/notify

Authentication

This endpoint requires a valid API key with canSendNotifications permission. The API key must be passed in the X-API-Key header.

Required Header

X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Path Parameters

Parameter	Type	Required	Default	Description
`order_id`	string	Yes	-	Order identifier (UUID by default, or Shopify order ID numeric portion if use_shopify_order_id is true in request body)

Request Body

Parameter	Type	Required	Default	Description
`channels`	string[]	Yes	-	Notification channels to use: "email", "sms", "whatsapp". At least one channel is required to prevent accidental notifications.
`use_shopify_order_id`	boolean	No	false	Set to 'true' to look up order using Shopify order ID. Extract the number from Shopify's GID format (gid://shopify/Order/450789469 → 450789469) and use it in the URL path

Response

Returns detailed notification results:

200 OK - Success Response

{
  "success": true,
  "data": {
    "message": "string",
    "order_id": "string",
    "notifications_sent": {
      "email": "string",
      "sms": "string",
      "whatsapp": "string"
    }
  }
}

Response Fields

Root Response Object

Field	Type	Description
`success`	boolean	Always true on a successful response.
`data`	object	The endpoint's payload. Its fields are listed in the tables below.
`message`	string	Confirmation message
`order_id`	string	UUID of the order
`notifications_sent`	object	Object containing notification status for each channel

Notifications Sent Object Fields

Field	Type	Description
`email`	string	Email notification status: "sent", "skipped", or "failed"
`sms`	string	SMS notification status: "sent", "skipped", or "failed"
`whatsapp`	string	WhatsApp notification status: "sent", "skipped", or "failed"

Examples

Basic Request (UUID)

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10/notify" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"8c1d4e2f-0a53-49b7-b6e4-7f2d9c3a5e10","use_shopify_order_id":false,"type":"email","message":"string"}'

Using Shopify Order ID

cURL Request

curl -X POST "https://api.ultimate-custom-order-status.apps.msmtech.ca/api/v1/orders/5460132438316/notify" \
  -H "X-API-Key: ucos_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "X-API-Version: 1.5" \
  -H "Content-Type: application/json" \
  -d '{
    "channels": ["email"],
    "use_shopify_order_id": true
  }'

Rate Limiting

This endpoint is subject to per-minute and per-day rate limits based on your API key. Rate limit information is returned in the response headers:

X-RateLimit-Limit-Minute: Maximum requests per minute
X-RateLimit-Remaining-Minute: Remaining requests in current minute
X-RateLimit-Reset-Minute: Unix timestamp when minute window resets
X-RateLimit-Limit-Day: Maximum requests per day
X-RateLimit-Remaining-Day: Remaining requests in current day
X-RateLimit-Reset-Day: Unix timestamp when day window resets
Retry-After: Seconds to wait before retrying (when rate limited)

Error Responses

400 Bad Request

Invalid request body

400 Bad Request

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "errors": [
      {
        "code": "invalid_type",
        "expected": "string",
        "received": "undefined",
        "path": [
          "status_id"
        ],
        "message": "Required"
      }
    ]
  }
}

401 Unauthorized

Missing or invalid API key

401 Unauthorized

{
  "success": false,
  "error": "Missing API key. Include it in the X-API-Key header"
}

403 Forbidden

API key lacks required permissions

403 Forbidden

{
  "success": false,
  "error": "Insufficient permissions. Required: canSendNotifications"
}

404 Not Found

Order not found

404 Not Found

{
  "success": false,
  "error": "Order not found"
}

500 Internal Server Error

Server error occurred

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error",
  "details": {
    "message": "An unexpected error occurred"
  }
}