Create a shipment event

Request

When a shipment status changes (e.g. it is shipped or out for delivery), notify Onward of that event.

Security

api_key

Path

shopShipmentIdstringrequired

Your unique ID for the Shipment (the same shop_shipment_id you sent when creating it)

Content-Typestringrequired

Content-Type must be application/json

Example:application/json

Acceptstringrequired

Accept must be application/json

Example:application/json

Bodyapplication/jsonrequired

shop_shipment_event_idstringrequired

Your identifier for the Shipment Event. Must be unique within its Shipment and stable over time — Onward uses it to look up and de-duplicate events within a shipment, so the same value must always refer to the same event.

Example:"817391"

statusstringrequired

Enum:"label_printed""label_purchased""attempted_delivery""ready_for_pickup""ready_for_recipient_pickup""carrier_picked_up""confirmed""in_transit""out_for_delivery""delivered"

Example:"in_transit"

messagestring

estimated_delivery_atstring, (date-time)

Carrier's estimated delivery date/time. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing Z (as in the example); timezone offsets such as -08:00 are also accepted.

Example:"2024-11-26T17:32:28Z"

created_atstring, (date-time)required

When the event occurred in your e-comm platform. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing Z (as in the example); timezone offsets such as -08:00 are also accepted.

Example:"2024-11-26T17:32:28Z"

curl -i -X POST \
  'https://app.useonward.com/api/v1/shipments/{shopShipmentId}/events' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "shop_shipment_event_id": "817391",
    "status": "in_transit",
    "message": "string",
    "estimated_delivery_at": "2024-11-26T17:32:28Z",
    "created_at": "2024-11-26T17:32:28Z"
  }'

Responses

Shipment event created successfully

Bodyapplication/json

shop_shipment_event_idstringrequired

Your identifier for the Shipment Event. Must be unique within its Shipment and stable over time — Onward uses it to look up and de-duplicate events within a shipment, so the same value must always refer to the same event.

Example:"817391"

statusstringrequired

Enum:"label_printed""label_purchased""attempted_delivery""ready_for_pickup""ready_for_recipient_pickup""carrier_picked_up""confirmed""in_transit""out_for_delivery""delivered"

Example:"in_transit"

messagestring

estimated_delivery_atstring, (date-time)

Carrier's estimated delivery date/time. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing Z (as in the example); timezone offsets such as -08:00 are also accepted.

Example:"2024-11-26T17:32:28Z"

created_atstring, (date-time)required

When the event occurred in your e-comm platform. Must be a valid ISO 8601 / RFC 3339 timestamp. Send it in UTC with a trailing Z (as in the example); timezone offsets such as -08:00 are also accepted.

Example:"2024-11-26T17:32:28Z"

Response

{
  "shop_shipment_event_id": "817391",
  "status": "in_transit",
  "message": "string",
  "estimated_delivery_at": "2024-11-26T17:32:28Z",
  "created_at": "2024-11-26T17:32:28Z"
}