RaiseAlerts raises alerts against fulfillment orders, using the same alert model the rest of Zentail already shows on a customer order.

POST

/v2/shipping/fulfillment_orders/alerts

curl --request POST \
  --url https://api.zentail.com/v2/shipping/fulfillment_orders/alerts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "alerts": [ { "fulfillmentOrderId": "example", "type": "ALERT_TYPE_UNSPECIFIED", "message": "example", "lineItemId": "example" } ] }'

Idempotent by design: Zentail refuses a second open alert of the same type on the same order, so a poller can raise the same condition every pass without creating noise. No client-side “have I already alerted?” bookkeeping.

An alert is not a substitute for rejecting. Raise one to explain a delay; reject when you are not going to ship.

Authorizations

• zentail_oauth
  sales:orders:fulfillment:self

Request Body^required

Media typeapplication/json

object

alerts

One entry per condition to raise. Required and server-capped, like every batch on this contract. Safe to re-send the same alerts every poll: a second open alert of the same type on the same order is not created.

Array<object>

object

fulfillmentOrderId

The fulfillment order the problem is on. An alert is always about one piece of work; there is no integration-wide alert — IntegrationStatus is where that belongs.

string

type

AlertType maps to Zentail’s customer-order alert types. Only the types a fulfillment integration can legitimately raise are exposed.

• ALERT_TYPE_UNSPECIFIED: Refused. Every alert names a type.
• ALERT_TYPE_FULFILL: Something is blocking fulfilment but you have not given up on it. If you have, reject instead.
• ALERT_TYPE_LATE_SHIPMENT: Will miss, or has missed, the ship-by deadline.
• ALERT_TYPE_LOST: Shipped but the package is lost in transit.
• ALERT_TYPE_OTHER: Anything else worth telling a user about. Put the specifics in message — it is the only thing that reaches a person.

string

default: ALERT_TYPE_UNSPECIFIED

Allowed values: ALERT_TYPE_UNSPECIFIED ALERT_TYPE_FULFILL ALERT_TYPE_LATE_SHIPMENT ALERT_TYPE_LOST ALERT_TYPE_OTHER

message

Shown to the user. Say what is wrong and what would fix it.

string

lineItemId

Optional: scope the alert to one line.

string

Responses

200

A successful response.

Media typeapplication/json

object

results

One result per alert sent, keyed by fulfillment order and type. Read already_open before reacting to anything: on a steady-state poller most entries are re-raises of a condition that has not gone away.

Array<object>

object

fulfillmentOrderId

The fulfillment order the alert was raised against, echoed back.

string

type

AlertType maps to Zentail’s customer-order alert types. Only the types a fulfillment integration can legitimately raise are exposed.

• ALERT_TYPE_UNSPECIFIED: Refused. Every alert names a type.
• ALERT_TYPE_FULFILL: Something is blocking fulfilment but you have not given up on it. If you have, reject instead.
• ALERT_TYPE_LATE_SHIPMENT: Will miss, or has missed, the ship-by deadline.
• ALERT_TYPE_LOST: Shipped but the package is lost in transit.
• ALERT_TYPE_OTHER: Anything else worth telling a user about. Put the specifics in message — it is the only thing that reaches a person.

string

default: ALERT_TYPE_UNSPECIFIED

Allowed values: ALERT_TYPE_UNSPECIFIED ALERT_TYPE_FULFILL ALERT_TYPE_LATE_SHIPMENT ALERT_TYPE_LOST ALERT_TYPE_OTHER

success

True when an open alert of this type exists on the order, whether this call created it or found it already there. False is a real failure.

boolean

errorMessage

Why it failed, in prose, for logs and support. Empty on success. A missing message and a type an integration may not raise both land here.

string

alreadyOpen

True when an open alert of this type already existed, so nothing was created. Treat as success — this is the expected steady state for a poller re-raising a condition that has not gone away.

boolean

Example

{
  "results": [
    {
      "type": "ALERT_TYPE_UNSPECIFIED"
    }
  ]
}

default

An unexpected error response.

Media typeapplication/json

object

code

integer format: int32

message

string

details

Array<object>

object

@type

string

key

additional properties

Example^generated

{
  "code": 1,
  "message": "example",
  "details": [
    {
      "@type": "example"
    }
  ]
}