Carrier events

Paxon's harmonised carrier milestones and events for track-and-trace, with the event payload mapping and JSON samples.

Overview

Paxon harmonises shipment tracking events from the various TMS and carrier systems it works with into a single set of milestones and events. These power track-and-trace in the Paxon Client Portal, and clients can optionally subscribe to them through a webhook.

To receive carrier events, create an endpoint URL that accepts the JSON structure described below. The Paxon system posting the payload only requires an HTTP 200 response from your receiving endpoint.

Milestones

Multiple event codes are grouped under a milestone code, giving a high-level status for a parcel as it moves through fulfilment and delivery.

Events

Carrier event codes identify the exact status of an order or shipment. The table below maps each event to its milestone. Events up to the Despatched milestone reflect Paxon order statuses as the order progresses through the outbound warehouse process.

Milestone code	Milestone	Event code	Event
10	Received	10	Order Received
10	Received	20	Order Acknowledged
50	In Process	50	Order Allocated
50	In Process	55	Order In Packing
50	In Process	60	Order Packed
50	In Process	70	Order Loaded
40	Cancelled	40	Order Cancelled
100	Despatched	100	Order Despatched
150	Available for pickup	150	Available for pickup
200	Delivered	200	Delivered
200	Delivered	201	Item Picked Up
200	Delivered	202	Delivered to Neighbour
200	Delivered	203	Delivered using special instruction
200	Delivered	204	Partially Delivered
400	On Hold	400	Custom clearance on hold
400	On Hold	401	Delivery attempted
400	On Hold	402	Technical Issue
400	On Hold	403	Issue with delivery address
400	On Hold	404	Delivery on hold
410	Delivery failed	410	Delivery failed
410	Delivery failed	411	Refused by Customer
410	Delivery failed	412	Not collected in time
410	Delivery failed	413	Issue with delivery address
410	Delivery failed	414	Damaged
410	Delivery failed	415	Delivery Cancelled

Event payload

Each carrier event is a JSON object. The fields below describe the payload; the Availability column notes which events carry each field.

Attribute	Type	Description	Availability
`olpnId`	VARCHAR(50)	Parcel OLPN id from the warehouse system, e.g. `00000999990151828538`.	Event codes > 100
`orderId`	VARCHAR(55)	Paxon order id, e.g. `DE8403638_PAXON`.	All event codes
`distributionCentre`	VARCHAR(15)	Facility code where the order is processed, e.g. `EEPL01`.	All event codes
`clientOrderId`	VARCHAR(40)	Webstore order id, e.g. `DE8403638`.	All event codes
`despatchedAt`	Timestamp	Despatch timestamp, e.g. `2022-05-17T00:00:00+01:00`.	Event code 100 only
`estimatedWeight`	Float	Estimated weight, e.g. `1.4`.	Event code 100 only
`length`	Float	Parcel length, e.g. `10.5`.	Event code 100 only
`width`	Float	Shipment width, e.g. `6.4`.	Event code 100 only
`height`	Float	Shipment height, e.g. `5.5`.	Event code 100 only
`weightUom`	VARCHAR(2)	Unit of measurement for weight, e.g. `kg`.	Event code 100 only
`dimensionUom`	VARCHAR(2)	Unit of measurement for dimensions, e.g. `cm`.	Event code 100 only
`destinationCountry`	VARCHAR(2)	ISO 2 code for the destination country, e.g. `DE`.	Event code 100 only
`destinationPostalCode`	VARCHAR(20)	Destination postal code, e.g. `06116`.	Event code 100 only
`carrierCode`	VARCHAR(20)	Carrier code, e.g. `UPS`.	All event codes
`carrierServiceCode`	VARCHAR(20)	Carrier service code, e.g. `STD`.	All event codes
`carrierTrackingNumber`	VARCHAR(50)	Consignment number for the shipment, e.g. `003VA000436699`.	Event codes > 100
`carrierTrackingUrl`	VARCHAR(255)	Tracking URL for the shipment, e.g. `https://track.carrier.example/0031V000436699`.	Event code 100 only
`MilestoneCode`	VARCHAR(5)	Paxon carrier milestone code, e.g. `100`.	All event codes
`MilestoneDesc`	VARCHAR(100)	Paxon carrier milestone description, e.g. `Despatched`.	All event codes
`EventCode`	VARCHAR(5)	Paxon carrier event status code, e.g. `100`.	All event codes
`EventDesc`	VARCHAR(100)	Paxon carrier event status description, e.g. `Order Despatched`.	All event codes
`sourceEventCode`	VARCHAR(5)	Event code from the TMS, e.g. `275`.	All event codes
`sourceEventDesc`	VARCHAR(100)	Event description from the TMS, e.g. `Scanned on delivery Hub`.	All event codes
`parcelTmsReference`	VARCHAR(50)	TMS reference, e.g. `LTN198209658N1`.	Event codes > 100
`tmsServiceCode`	VARCHAR(20)	Service code from the TMS, e.g. `LGINTUPST`.	Event codes > 100
`location`	VARCHAR(100)	Carrier event location, e.g. `Halle, Germany`.	Event codes > 100 if available from TMS
`latitude`	VARCHAR(20)	Carrier event location latitude, e.g. `51.523252269137`.	Event codes > 100 if available from TMS
`longitude`	VARCHAR(20)	Carrier event location longitude, e.g. `-0.1146692876584629`.	Event codes > 100 if available from TMS

JSON samples

Five representative events span the parcel lifecycle:

Event code	Event
10	Order Received
50	Order Allocated
60	Order Packed
100	Order Despatched
200	Delivered

A Despatched (event code 100) payload looks like this:

{
  "orderId": "DE8403638_PAXON",
  "clientOrderId": "DE8403638",
  "olpnId": "00000999990151828538",
  "distributionCentre": "EEPL01",
  "despatchedAt": "2022-05-17T00:00:00+01:00",
  "estimatedWeight": 1.4,
  "length": 10.5,
  "width": 6.4,
  "height": 5.5,
  "weightUom": "kg",
  "dimensionUom": "cm",
  "destinationCountry": "DE",
  "destinationPostalCode": "06116",
  "carrierCode": "UPS",
  "carrierServiceCode": "STD",
  "carrierTrackingNumber": "003VA000436699",
  "carrierTrackingUrl": "https://track.carrier.example/0031V000436699",
  "MilestoneCode": "100",
  "MilestoneDesc": "Despatched",
  "EventCode": "100",
  "EventDesc": "Order Despatched",
  "sourceEventCode": "275",
  "sourceEventDesc": "Scanned on delivery Hub"
}

Webhooks — register an endpoint to receive these events.
Integration flow — where carrier events fit end to end.