Skip to main content
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.