OTEP — Open Tracking Event Protocol

Status: Draft v0.1 · An open, vendor-neutral specification · License: open (see §10)

OTEP is an open, vendor-neutral protocol for the lifecycle of any trackable subject. It defines one event model and one status vocabulary so that tracking events from any source — own-fleet delivery, third-party couriers, carrier labels and beyond — can be exchanged, understood and projected to international standards without re-integrating for every party.

This document is the specification: the structure, the fields, the status tables, the state machine, the external-standard mappings, and the conformance rules for building a compliant implementation. It is implementation-agnostic — it describes the protocol, not any particular vendor's internals. RFC-2119 keywords (MUST / SHOULD / MAY) are normative.

1. What OTEP solves

Tracking is fragmented: every carrier names fields and status codes differently, every delivery channel reports in its own shape, and connecting to global standards means re-integrating again and again. OTEP gives producers and consumers a single common language: a producer emits OTEP events once, and every OTEP consumer understands them and can project them to the standard it needs.

2. Design principles

1. Event-sourced. The event timeline is the source of truth; "current status" is always a projection — the status of the latest event.
2. What / When / Where / Why. Every event is shaped around these four dimensions — the same dimensions shared by GS1 EPCIS, IATA ONE Record and UN/CEFACT — so those standards are output projections of an OTEP event rather than parallel models.
3. No-list sources are not a blocker. A source that exposes only a current status (no history) is handled by synthesizing one event per observed change (§5).
4. Additive. OTEP is exposed alongside any existing tracking API; adopting it never requires a breaking change to what consumers already use.

3. The OTEP timeline

A timeline is an envelope carrying the tracked subject and an ordered list of events.

{
  "otep_version": "0.1",
  "profile": "parcel",                  // domain profile (§8)
  "subject": {
    "tracking_number": "SR123...",      // ≥1 identifier required
    "order_id": 12345,                  // optional
    "package_id": 67890,                // optional
    "external_tracking_number": "1Z...",// optional
    "gs1_sscc": "00...",                // optional — enables EPCIS epcList
    "piece_id": "..."                   // optional — enables ONE Record linkage
  },
  "current_status": "delivered",        // projection of the latest event
  "delivered": true,
  "events": [ /* OTEP events, §4 */ ]
}

The OTEP event

{
  // WHAT — carried once at the timeline level (subject above)

  // WHEN
  "occurred_at": "2026-06-10T09:30:00-04:00",  // event instant, ISO-8601 with offset
  "recorded_at": "2026-06-10T09:45:23-04:00",  // ingestion instant (optional)
  "time_type": "actual",                        // actual | estimated | scheduled

  // WHERE
  "location": {
    "name": "Toronto Hub",
    "code": "YYZ-2",
    "gln": "0614141000005",                     // GS1 GLN → EPCIS SGLN
    "lat": 43.6777, "lng": -79.6248,
    "country": "CA"                             // ISO 3166-1 alpha-2
  },

  // WHY / WHAT HAPPENED
  "status_code": "out_for_delivery",            // an OTEP status code (§4)
  "phase": "out_for_delivery",                  // derived from status_code
  "incident_reason": null,                       // an OTEP incident reason (§4) when exception

  // WHO
  "actor": { "type": "driver", "name": "Jane D.", "phone": "+1..." },

  // PROVENANCE
  "source": {
    "type": "self_delivery",                    // self_delivery | third_party_delivery | carrier_label
    "provider_id": null,
    "carrier_code": null,
    "external_event_code": null,                 // your raw status code (preserve it)
    "raw": { /* original payload */ }
  },

  // PROOF
  "pod": {
    "photos": [ { "url": "...", "content_base64": null } ],
    "signature": [ { "url": "...", "content_base64": null } ],
    "recipient": "John Smith"
  }
}

Every field except subject, occurred_at, status_code and source is optional — partial sources fill what they have. Node/hub scans set location to the scanning facility. High-frequency GPS telemetry is NOT an OTEP event; an event is emitted on a status change or a node scan.

4. Vocabulary

4.1 Status codes

20 canonical lifecycle codes. phase is always derivable from the code.

code	phase	terminal	POD	meaning
information_submitted	pre_shipment			order info received
booking_confirmed	pre_shipment			carrier/booking acknowledged
awaiting_pickup	pre_shipment			ready for collection
out_for_pickup	pickup			en route to pick up
picked_up	pickup		✓	collected from shipper
pickup_failed	exception			pickup attempt failed
pickup_rescheduled	exception			pickup will retry
received	inbound			received at facility
arrival_scan	inbound			arrival scan at node
in_transit	transit			moving
package_outbound	transit			departed facility
removed_from_route	exception			taken off route
route_cancelled	exception			route cancelled
out_for_delivery	out_for_delivery			on the vehicle
delivered	delivered	✓	✓	delivered to consignee
delivery_failed	exception			delivery attempt failed
delivery_rescheduled	exception			will retry / redeliver
return_to_sender	return	✓		returning to origin
rejected_by_recipient	return	✓		recipient refused
cancelled	return	✓		order cancelled

4.2 Phases

pre_shipment · preparing · pickup · inbound · in_custody · transit · out_for_delivery · delivered · exception · return. (preparing and in_custody are reserved for non-parcel profiles — §8.)

4.3 Source types & time types

source.type: self_delivery · third_party_delivery · carrier_label. time_type: actual · estimated · scheduled (default actual).

4.4 Incident reasons

When an event is in the exception phase it SHOULD carry an incident_reason from this normalized vocabulary:

• Carrier: carrier_damaged_parcel, carrier_sorting_error, carrier_address_not_found, carrier_parcel_lost, carrier_not_enough_time, carrier_vehicle_issue, carrier_capacity_exceeded, carrier_mechanical_delay
• Retailer/shipper: retailer_cancelled, retailer_incorrect_data, retailer_not_ready, retailer_incorrect_parcel, retailer_incorrect_dimensions, retailer_packaging_issue
• Consignee: consignee_refused, consignee_business_closed, consignee_not_available, consignee_not_home, consignee_cancelled, consignee_verification_failed, consignee_incorrect_address, consignee_access_restricted, consignee_safe_place_unavailable
• Customs: customs_delay, customs_documentation, customs_duties_unpaid, customs_prohibited, customs_inspection
• Force majeure: weather_delay, natural_disaster, force_majeure
• Other: parcel_being_researched, security_issue, regulatory_hold, unknown

5. State machine & status-only sources

Phases advance forward; exceptions interrupt and resolve back. Terminal states (delivered, return_to_sender, rejected_by_recipient, cancelled) close the subject.

pre_shipment → preparing → pickup → inbound → in_custody → transit → out_for_delivery → delivered ✓
                                       └──────────── exception ──────────┘
                                       └──────────── return / cancelled ✓

Rules:

• Consumers MUST order events by occurred_at and MUST tolerate out-of-order arrival.
• Transitions into a terminal state are idempotent; repeats are deduped.
• After a terminal status, a producer MUST NOT emit further events except a documented RMA / re-open flow.
• A source exposing only a current status MUST synthesize one event per observed change (with a stable dedupe key) rather than omit history. Over time the snapshots accumulate into a timeline.

6. External-standard mappings

OTEP's four dimensions line up field-for-field with the major standards, so each is an output projection of an OTEP event.

OTEP	GS1 EPCIS 2.0	IATA ONE Record	UN/CEFACT
occurred_at (+offset)	eventTime + eventTimeZoneOffset	eventDate + eventTimeType=Actual	Event Date/Time
recorded_at	recordTime	recordedAt	—
subject (sscc/piece)	epcList (SSCC URN)	linkedObject → Piece/Shipment	Consignment
location (gln/lat/lng)	readPoint / bizLocation (SGLN)	recordedAtLocation → Location	Location
status_code	bizStep + disposition	eventCode	Transport status code
actor	sourceList / extension	Actor / Party	Party
incident_reason	disposition / ErrorDeclaration	event remark	Status reason code

Per-code values (EPCIS CBV bizStep/disposition, ONE Record eventCode, UN/CEFACT code) are published in the machine-readable codebook. Beyond these international standards, an OTEP timeline can also be projected to OpenTelemetry traces, OGC SensorThings observations, and common commerce platforms (AfterShip, Shopify, Amazon, Walmart, BigCommerce, Magento, WooCommerce, Etsy).

Confidence: EPCIS CBV values are stable standard URNs. ONE Record and UN/CEFACT code values are best-fit for last-mile and should be validated against the official code lists before external use. "Delivered to consignee" has no exact CBV bizStep — the closest fit (receiving + received) is used, or a user-vocabulary extension URN.

7. The OTEP API

OTEP is consumed over a small read-only HTTP surface; all endpoints are public.

Verb	Path	Returns
GET	/api/v1/otep/trackings/{tracking_number}	the timeline for a tracking number
GET	/api/v1/otep/trackings/{tracking_number}/events	events only
POST	/api/v1/otep/trackings/batch	many tracking numbers in one call
POST	/api/v1/otep/validate	conformance check for a posted timeline (§9)

A GraphQL query exposing the same timeline is also available.

Content negotiation

The same timeline is serialized into whichever representation you request, via a ?format= query parameter or an Accept profile:

Request	Representation
?format=otep (default)	native OTEP timeline
?format=epcis	GS1 EPCIS 2.0 (JSON-LD ObjectEvents)
?format=onerecord	IATA ONE Record (LogisticsEvents)
?format=uncefact	UN/CEFACT transport status
?format=otlp	OpenTelemetry traces
?format=sensorthings	OGC SensorThings observations
?format=aftership | shopify | amazon | walmart | bigcommerce | magento | woocommerce | etsy	the platform's tracking/fulfillment shape

Events that cannot be assigned a code in a projection are skipped and counted (never silently dropped).

8. Domain profiles

OTEP is a general protocol, not a parcel one. The protocol layer (event envelope, phase spine, state machine) is universal; concrete status codes belong to a profile declared on the timeline via profile. The codes in §4 are the parcel profile. Other domains — moving, food delivery, storage and beyond — add their own code sets under their profile, namespaced otep:<profile>:<code>, each mapping up to the same phase spine. Adding a profile is an extension, not a protocol change.

9. Conformance specification (normative)

A producer or consumer is OTEP-conformant when every event it emits or accepts satisfies these tables and rules.

9.1 Timeline envelope

Field	Type	Req.	Constraints
otep_version	string	MUST	semver, e.g. 0.1
profile	string	MUST	a registered profile
subject	object	MUST	§9.2
current_status	string|null	SHOULD	a status code (§4)
current_phase	string|null	SHOULD	MUST equal the phase of current_status if both present
delivered	boolean	SHOULD	true iff current_status = delivered
events	array	MUST	event objects (§9.3), orderable by occurred_at

9.2 subject

At least ONE of tracking_number / order_id / package_id MUST be present.

Field	Type	Constraints
tracking_number	string	non-empty
order_id / package_id	integer|null
external_tracking_number	string|null
gs1_sscc	string|null	18 digits
piece_id	string|null

9.3 Event object

#	Field	Type	Req.	Constraints
1	occurred_at	string	MUST	ISO-8601 with offset
2	recorded_at	string|null	SHOULD	ISO-8601
3	time_type	string	MAY (default actual)	actual | estimated | scheduled
4	status_code	string|null	MUST¹	a code in §4.1
5	phase	string|null	SHOULD	MUST equal the phase of status_code
6	incident_reason	string|null	SHOULD²	a reason in §4.4
7	description	string|null	MAY	human-readable
8	location	object|null	MAY	§9.4
9	actor	object|null	MAY	{ type, name?, phone? }; type ∈ {driver, operator, carrier, system}
10	source	object	MUST	§9.5
11	pod	object|null	MAY³	{ photos[], signature[], recipient? }

¹ A coded event MUST carry a status code from §4.1. A raw scan you cannot yet classify MAY set status_code = null, but MUST preserve the native code in source.external_event_code and MUST be counted, never dropped. ² An exception-phase event SHOULD carry an incident_reason. ³ Events with status_code ∈ {delivered, picked_up} SHOULD carry a pod.

9.4 location

name (string) · code (string) · gln (GS1 GLN, 13 digits) · lat / lng (WGS-84) · country (ISO 3166-1 alpha-2). All optional.

9.5 source

Field	Type	Req.	Constraints
type	string	MUST	self_delivery | third_party_delivery | carrier_label
provider_id	integer|null	MAY
carrier_code	string|null	MAY
external_event_code	string|null	SHOULD⁴	your raw status code
raw	object|null	MAY	original payload

⁴ MUST be present when status_code is null, so the native code is never lost.

9.6 Rules

1. Time. occurred_at MUST parse as ISO-8601. Normalize numeric epochs and .NET /Date(ms)/ on ingest; do not emit those forms.
2. Ordering / dedup. Consumers MUST sort by occurred_at, tolerate out-of-order arrival, and dedupe on (subject, status_code, occurred_at).
3. State machine. After a terminal status, do not emit further events except a documented RMA / re-open.
4. No silent loss. Events that cannot be coded MUST be counted, never dropped.
5. Derivation. phase, current_status, current_phase, delivered are projections — if present they MUST be consistent with the event timeline.

9.7 Conformance levels & validation

• Level 1 — emits the envelope (§9.1), events with the required fields (§9.3), valid status codes (§4.1), valid phases (§4.2), and honors the state machine (§5).
• Level 2 — additionally emits at least one external-standard projection (§6) and, where applicable, profile-specific codes (§8).

Verify your output by POSTing a timeline to POST /api/v1/otep/validate. Treat any errors as blocking; address warnings. A machine-readable JSON Schema and the complete codebook (every status code, phase and external mapping) are published for offline validation.

10. Openness & governance

OTEP is an open specification, free for any party to implement.

• Normative vs informative. Normative: the event envelope, phase spine, status vocabulary, state machine and external-standard field mappings. How an implementer binds OTEP to its own internal systems is its own concern and out of scope here.
• Stable identifiers. Codes are addressed as otep:<profile>:<code>, phases as otep:phase:<name>. Once published in a released version, an identifier's meaning is immutable.
• Versioning. Semantic versioning. Adding codes/profiles is a MINOR (backward-compatible) change; changing the meaning of an existing code is a MAJOR change and SHOULD be avoided. The protocol version travels with every timeline (otep_version).
• Extension. New profiles and codes are proposed against this spec rather than forked, so independent implementers converge. Experimental codes MAY use an x- prefix (otep:parcel:x-my_code) until registered.
• License. The specification is intended to be released under an open license — TBD, pending sign-off.

11. Vendor interoperability — bring your own standard

OTEP welcomes other vendors to bring their own tracking-event standard so OTEP can interoperate with it, in either direction:

• Project OTEP → your standard. Define a mapping from an OTEP timeline to your format, reusing the OTEP status vocabulary. It is a pure transformation — timeline in, your structure out — so the mapping is written once and every OTEP producer can emit your format.
• Map your standard → OTEP. Provide a crosswalk from your status vocabulary onto the OTEP codes (§4) plus, if needed, a profile (§8). Your raw codes are preserved in source.external_event_code; unmapped codes are counted, never dropped.

Even if you cannot adopt OTEP directly, you are welcome to add a single normalized otep_status to your own API responses and to share your tracking event codes for crosswalk mapping. Propose mappings against this spec (rather than forking) so implementers converge; new formats plug into the same ?format= content negotiation and never break an existing consumer.