Carrier events flow into Perform.AI automatically. POST /v5/events/create/ adds manual events on top — steps carriers can’t see: warehouse handling, quality checks on returns, refund progress. Manual events appear everywhere carrier events do: tracking pages, notifications, webhooks, and the Parcel Details timeline. Full specs: API reference.
Prerequisites
The Shipment must already have a tracking_number and an assigned carrier — otherwise the request is rejected with Manual events cannot be created for shipment as a tracking_number and carrier has not been assigned. (For Return Shipments, the Return Booking Service assigns both when the label is generated.)
The request
Identify the Shipment by shipment_uuid or shipment_id in the body; events is a required array:
Each event carries either a free-text description (max 250 chars) or a standard_key — a Perform.AI standard event key (e.g. H11) that maps the event to the standard taxonomy and phases. The key list is available from your account team.
Rules that matter:
- If both
description and standard_key are sent, standard_key wins and the description is ignored — the response is a 299 warning, not an error.
date_time defaults to now (UTC) when omitted; send an explicit offset or Z for local times.- If you send a
location, its place is required.
- Events are added, never replaced — there is no way to edit or delete an event via the API, so validate before sending.
- A Pending outbound Shipment becomes Active, Delivered, or Undeliverable when its first event lands, depending on the event.
For Return Shipments, use description values your customers understand — for example: Quality check in progress, Quality check processed - items accepted, Refund being processed, Refund successfully processed.
The response
Success carries no data payload:
A 299 means the events were created but something was adjusted (see warnings); a 4030 means nothing was created — most commonly the missing tracking-number/carrier precondition, a missing description/standard_key, or an unrecognized standard key. 
