Tracking data model

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

FieldTypeRequiredDescription
idstringNoUnique identifier for this tracking object
created_atstring (date-time)NoThe date that this tracking object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)NoThe last date that this tracking object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
shipment_idstringNoReference to the shipment
tracking_numberstringNoTracking number for the shipment
statusenumNoCurrent status of the shipment Values: PENDING, PROCESSING, IN_TRANSIT, DELIVERED, EXCEPTION, CANCELLED, LABEL_CREATED, PICKED_UP, OUT_FOR_DELIVERY, DELIVERY_ATTEMPTED, RETURNED_TO_SENDER, HELD_AT_LOCATION, CUSTOMS_CLEARANCE, EXCEPTION_RESOLVED
eventsShippingTrackingEvent[]NoArray of tracking events
events[].created_atstring (date-time)NoThe date that this tracking event object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
events[].descriptionstringNoDescription of the tracking event
events[].statusenumNoStatus at the time of this event Values: PENDING, PROCESSING, IN_TRANSIT, DELIVERED, EXCEPTION, CANCELLED, LABEL_CREATED, PICKED_UP, OUT_FOR_DELIVERY, DELIVERY_ATTEMPTED, RETURNED_TO_SENDER, HELD_AT_LOCATION, CUSTOMS_CLEARANCE, EXCEPTION_RESOLVED
events[].event_codestringNoCarrier-specific event code
events[].carrier_status_codestringNoCarrier's status code at this event
events[].location_addressShippingTrackingEvent_location_addressNo
events[].location_address.address1stringNo
events[].location_address.address2stringNo
events[].location_address.citystringNo
events[].location_address.regionstringNo
events[].location_address.region_codestringNo
events[].location_address.postal_codestringNo
events[].location_address.countrystringNo
events[].location_address.country_codestringNoISO 2-digit country code
events[].location_address.namestringNoRecipientsender name
events[].location_address.company_namestringNoCompany name (for commercial addresses)
events[].location_address.telephonestringNoPhone number (required by FedEx, UPS, DHL)
events[].location_address.emailstringNoEmail address (for delivery notifications)
events[].location_address.is_residentialbooleanNoAlias for address_type === 'RESIDENTIAL'
events[].location_address.is_validatedbooleanNoWhether address has been validated
events[].location_address.delivery_instructionsstringNoSpecial delivery notes
events[].location_idstringNoLocation ID; points to CommerceLocation (reference to ShippingLocation)
events[].location_namestringNoLocation name
events[].notesstringNoAdditional notes
events[].signed_bystringNoWho signed for delivery
estimated_deliverystring (date-time)NoEstimated delivery date
actual_delivery_atstring (date-time)NoActual delivery timestamp (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
status_descriptionstringNoHuman-readable status
carrier_idstringNoReference to the carrier
carrier_status_codestringNoCarrier's status code
carrier_status_descriptionstringNoCarrier's status description

TypeScript

TypeScript
export type ShippingTracking = {
	id?: string; // Unique identifier for this tracking object
	created_at?: string-time; // The date that this tracking object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // The last date that this tracking object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	shipment_id?: string; // Reference to the shipment
	tracking_number?: string; // Tracking number for the shipment
	status?: 'PENDING' | 'PROCESSING' | 'IN_TRANSIT' | 'DELIVERED' | 'EXCEPTION' | 'CANCELLED' | 'LABEL_CREATED' | 'PICKED_UP' | 'OUT_FOR_DELIVERY' | 'DELIVERY_ATTEMPTED' | 'RETURNED_TO_SENDER' | 'HELD_AT_LOCATION' | 'CUSTOMS_CLEARANCE' | 'EXCEPTION_RESOLVED'; // Current status of the shipment
	events?: []; // Array of tracking events
	estimated_delivery?: string-time; // Estimated delivery date
	actual_delivery_at?: string-time; // Actual delivery timestamp (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	status_description?: string; // Human-readable status
	carrier_id?: string; // Reference to the carrier
	carrier_status_code?: string; // Carrier's status code
	carrier_status_description?: string; // Carrier's status description
	raw?: any; // The raw data returned by the integration for this tracking
} 

Zod

Zod
import { z } from 'zod';

export const ZodShippingTracking = z.object({
	id: z.string().optional().describe("Unique identifier for this tracking object"),
	created_at: z.string-time().optional().describe("The date that this tracking object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("The last date that this tracking object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	shipment_id: z.string().optional().describe("Reference to the shipment"),
	tracking_number: z.string().optional().describe("Tracking number for the shipment"),
	status: z.enum("PENDING", "PROCESSING", "IN_TRANSIT", "DELIVERED", "EXCEPTION", "CANCELLED", "LABEL_CREATED", "PICKED_UP", "OUT_FOR_DELIVERY", "DELIVERY_ATTEMPTED", "RETURNED_TO_SENDER", "HELD_AT_LOCATION", "CUSTOMS_CLEARANCE", "EXCEPTION_RESOLVED").optional().describe("Current status of the shipment"),
	events: z.array().optional().describe("Array of tracking events"),
	estimated_delivery: z.string-time().optional().describe("Estimated delivery date"),
	actual_delivery_at: z.string-time().optional().describe("Actual delivery timestamp (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	status_description: z.string().optional().describe("Human-readable status"),
	carrier_id: z.string().optional().describe("Reference to the carrier"),
	carrier_status_code: z.string().optional().describe("Carrier's status code"),
	carrier_status_description: z.string().optional().describe("Carrier's status description"),

});

Python

Python
import dataclasses

@dataclasses.dataclass
class ShippingTrackingStatus(str, Enum):
	PENDING = 'PENDING'
	PROCESSING = 'PROCESSING'
	IN_TRANSIT = 'IN_TRANSIT'
	DELIVERED = 'DELIVERED'
	EXCEPTION = 'EXCEPTION'
	CANCELLED = 'CANCELLED'
	LABEL_CREATED = 'LABEL_CREATED'
	PICKED_UP = 'PICKED_UP'
	OUT_FOR_DELIVERY = 'OUT_FOR_DELIVERY'
	DELIVERY_ATTEMPTED = 'DELIVERY_ATTEMPTED'
	RETURNED_TO_SENDER = 'RETURNED_TO_SENDER'
	HELD_AT_LOCATION = 'HELD_AT_LOCATION'
	CUSTOMS_CLEARANCE = 'CUSTOMS_CLEARANCE'
	EXCEPTION_RESOLVED = 'EXCEPTION_RESOLVED'

@dataclasses.dataclass
class ShippingTracking:
	"""Unique identifier for this tracking object"""
	id: Optional[str]
	"""The date that this tracking object was created (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""The last date that this tracking object was updated (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""Reference to the shipment"""
	shipment_id: Optional[str]
	"""Tracking number for the shipment"""
	tracking_number: Optional[str]
	"""Current status of the shipment"""
	status: Optional[ShippingTrackingStatus]
	"""Array of tracking events"""
	events: Optional[PropertyShippingTrackingEvents]
	"""Estimated delivery date"""
	estimated_delivery: Optional[str]
	"""Actual delivery timestamp (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	actual_delivery_at: Optional[str]
	"""Human-readable status"""
	status_description: Optional[str]
	"""Reference to the carrier"""
	carrier_id: Optional[str]
	"""Carrier's status code"""
	carrier_status_code: Optional[str]
	"""Carrier's status description"""
	carrier_status_description: Optional[str]
Are we missing anything? Let us know
Was this page helpful?