{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/ch-robinson-worldwide/main/json-schema/ch-robinson-worldwide-milestone-schema.json", "title": "milestone", "description": "Shipment update", "x-generated": "2026-10-20", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/ch-robinson-worldwide-shipments-api-openapi.yml#/components/schemas/milestone", "type": "object", "required": [ "eventCode", "dateTime", "shipmentIdentifier", "location" ], "properties": { "transitType": { "description": "Defines the type of movement the event is for.", "enum": [ "Road", "Ocean", "Rail", "Air" ] }, "eventCode": { "description": "Depending on the transitType you will use a code from one of the lists below.", "oneOf": [ { "$ref": "#/$defs/roadMilestoneEventCodeEnum" }, { "$ref": "#/$defs/oceanMilestoneEventCodeEnum" }, { "$ref": "#/$defs/railMilestoneEventCodeEnum" }, { "$ref": "#/$defs/airMilestoneEventCodeEnum" } ] }, "shipmentIdentifier": { "$ref": "#/$defs/shipmentIdentifier" }, "dateTime": { "$ref": "#/$defs/dateTime" }, "carrier": { "$ref": "#/$defs/milestoneCarrier" }, "location": { "$ref": "#/$defs/milestoneLocation" }, "items": { "type": "array", "description": "Array of items tied to the milestone.", "items": { "$ref": "#/$defs/milestoneItem" } }, "supplementalInformation": { "$ref": "#/$defs/supplementalInformation" } }, "$defs": { "airMilestoneEventCodeEnum": { "type": "string", "description": "Code that indicates the type of milestone being sent for a shipment being moved by plane. For a detailed description of all enumerated codes please find them here.", "enum": [ "ARR", "AWD", "AWR", "BKD", "CCD", "CRC", "DDL", "DEP", "DIS", "DLV", "FOH", "MAN", "NFD", "OCI", "OSI", "PRE", "RCF", "RCS", "RCT", "TFD", "TGC", "TRM", "ULD" ] }, "countryCodeEnum": { "type": "string", "description": "Indicate the country of the location. \n\nFor a detailed description of all enumerated codes please find them here.", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BM", "BN", "BO", "BR", "BS", "BT", "MM", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "RS", "CU", "CV", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GD", "GE", "GF", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IN", "IO", "IQ", "IR", "IS", "IT", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KP", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "MG", "MH", "MK", "ML", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "ST", "SV", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TP", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "GB", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZR", "ZW", "AX", "GG", "IM", "JE", "ME", "MF", "CW", "SX", "SS", "IC", "XC", "XL" ] }, "dateTime": { "type": "object", "description": "Object containing the different types of dates that can apply to a milestone. \n\n ### At least one needs to be present.", "properties": { "eventDateTime": { "type": "string", "format": "date-time", "description": "ISO8601 UTC date-time of the milestone for event code not pertaining to ETA or appointment." }, "estimatedTimeOfArrival": { "type": "string", "format": "date-time", "description": "ISO8601 UTC date-time when event code pertains to ETA." }, "appointmentWindow": { "type": "object", "description": "The date/time window when an appointment has been set. If there is no window, put the same date/time in both the openDateTime and closeDateTime fields.", "properties": { "openDateTime": { "type": "string", "format": "date-time", "description": "ISO8601 UTC date-time of earliest time carrier will be arriving." }, "closeDateTime": { "type": "string", "format": "date-time", "description": "ISO8601 UTC date-time of latest time carrier will be arriving." } } } } }, "flightDetail": { "type": "object", "description": "Identifies flight information.", "properties": { "flightNumber": { "type": "string", "description": "Identifies the flight number." }, "flightDepartureDateTime": { "type": "string", "format": "date-time", "description": "The date/time the flight departed." }, "flightCarrierCode": { "type": "string", "description": "Code associated to the flight provider." } } }, "lateCodeEnum": { "type": "string", "description": "C.H. Robinson defined code for a carrier being late to a stop or reason to schedule new appiontment. Here is a list of the most commonly used late reason codes: \n* `1` - Missed Delivery - Transportation carrier missed customer delivery\n* `3` - Returned to Shipper\n* `9` - Mechanical breakdown\n* `14` - Weather or Natural Disaster Related - Shipment delayed by natural disaster or severe weather\n\nFor a detailed description of all enumerated codes please find them here.", "enum": [ "1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "50", "51", "52", "53", "54", "55", "56", "57", "58", "59", "60", "61", "62", "63", "64", "65", "66", "67", "68", "69", "70", "71", "72", "73", "74", "75", "76", "77", "78", "79", "80", "81", "82", "83", "84", "85", "86", "87", "88", "89", "90", "CSC", "CSCCHR", "91", "92", "AE", "BH", "BO", "CA", "CR", "CSCCAR", "CSCCUS", "CSCEDI", "CSCREQ", "CSCWEA", "DR", "EE", "MA", "ME", "VI", "WR", "93", "94", "95", "96", "97", "98", "99", "100", "0" ] }, "milestoneCarrier": { "type": "object", "description": "Carrier information associated to the milestone.", "required": [ "name" ], "properties": { "name": { "type": "string", "minimum": 1, "maximum": 50, "description": "Name of carrier executing shipment." }, "milestoneSource": { "type": "string", "description": "Source of the milestone, if not sent by the carrier." }, "dotNumber": { "type": "string", "description": "United States of America government issued identification number for a carrier." }, "mcNumber": { "type": "string", "description": "A legal serialization each carrier has from an operating authority to operate their carrier business." }, "carrierCode": { "type": "string", "description": "C.H. Robinson defined code for the carrier. \n\n ### Although not a validation requirement, not having carrierCode could impact the update from applying to the shipment that is managed by C.H. Robinson." }, "scac": { "type": "string", "description": "In North America this is the Nmfta defined standard carrier alpha code." }, "sealNumber": { "type": "string", "description": "If trailer has a seal, the identifier of the seal." }, "temperature": { "type": "number", "format": "float", "description": "Idenifies the temperature at the time of the milestone." }, "temperatureUnitOfMeasure": { "$ref": "#/$defs/temperatureUomEnum" }, "vehicleDetail": { "$ref": "#/$defs/vehicleDetail" }, "flightDetail": { "$ref": "#/$defs/flightDetail" }, "vesselDetail": { "$ref": "#/$defs/vesselDetail" }, "railDetail": { "$ref": "#/$defs/railDetail" } } }, "milestoneItem": { "type": "object", "description": "Item totals associated to milestone.", "properties": { "itemId": { "type": "string", "description": "Unique identifier of line item." }, "weight": { "type": "number", "description": "Acutal weight of line item." }, "weightUnitOfMeasure": { "$ref": "#/$defs/weightUomEnum" }, "quantity": { "type": "number", "description": "Acutal quantity of line item." }, "pallets": { "type": "number", "description": "Quantity of pallet(s)." } } }, "milestoneLocation": { "type": "object", "description": "Location information associated to the milestone.", "required": [ "address" ], "properties": { "type": { "$ref": "#/$defs/milestoneStoptypeEnum" }, "stopSequenceNumber": { "type": "integer", "description": "Identifies the stop number the milestone is associated to. \n\n ### If location is for a milestone that isn't tied to a stop then this field should be set to null." }, "sequenceNumber": { "type": "integer", "description": "Identifies the sequence number the milestone is associated to. \n\n ### If location is for a milestone that isn't tied to a stop then this field should be set to null." }, "name": { "type": "string", "description": "Identifies the name of the location the milestone is associated to. If location is for a milestone that isn't tied to a stop then this field should be set to null." }, "locationId": { "type": "string", "description": "Milestone location identifier." }, "unlocationCode": { "type": "string", "description": "The UN Location Code for the milestone location.", "minimum": 1, "maximum": 10 }, "iata": { "type": "string", "description": "The IATA code for the milestone location." }, "address": { "$ref": "#/$defs/milestoneLocationAddress" } } }, "milestoneLocationAddress": { "type": "object", "description": "Contains address information; variant that does not require stateProvinceCode.", "required": [ "city", "country", "latitude", "longitude" ], "properties": { "addressLine1": { "type": "string", "description": "Line one of the address." }, "addressLine2": { "type": "string", "description": "Line two of the address." }, "city": { "type": "string", "description": "City name of address. \n\n ### Provide either (city and country) or (latitude and longitude); one complete set is required." }, "stateProvinceCode": { "description": "Indicate the state or province of the location.\n\n ### ***Though not required, it is preferred to clearly identify location where latitude and longitude is not provided.\n\nFor a detailed description of all enumerated codes please find them here.", "allOf": [ { "type": "string" }, { "$ref": "#/$defs/stateProvinceCodeEnum" } ] }, "postalCode": { "type": "string", "description": "Postal code of address." }, "country": { "description": "Indicate the country of the location. \n\n ### Provide either (city and country) or (latitude and longitude); one complete set is required.", "allOf": [ { "type": "string" }, { "$ref": "#/$defs/countryCodeEnum" } ] }, "latitude": { "type": "number", "format": "float", "minimum": -90, "maximum": 90, "description": "The decimal latitude of the address. \n\n ### Provide either (city and country) or (latitude and longitude); one complete set is required." }, "longitude": { "type": "number", "format": "float", "minimum": -180, "maximum": 180, "description": "The decimal longitude of the address. \n\n ### Provide either (city and country) or (latitude and longitude); one complete set is required." } } }, "milestoneStoptypeEnum": { "type": "string", "description": "Identifies the type of stop the milestone is referencing.\n### If location is for a milestone that isn't tied to a stop then this field should be set to null. \n- 'P' - Pick \n- 'OA' - Origin Airport \n- 'OP' - Origin Port \n- 'OR' - Origin Ramp \n- 'OT' - Origin Terminal \n- 'D' - Drop \n- 'DA' - Destination Airport \n- 'DP' - Destination Port \n- 'DR' - Destination Ramp \n- 'DT' - Destination Terminal \n- 'IA' - Intermediate Airport \n- 'IP' - Intermediate Port \n- 'IR' - Intermediate Ramp \n- 'X' - Cross Dock \n- 'OF' - Origin Forwarder \n- 'OC' - Origin Crossdock \n- 'DF' - Destination Forwarder \n- 'DC' - Destination Crossdock \n- 'DY' - Dropyard", "enum": [ "P", "OA", "OP", "OR", "OT", "D", "DA", "DP", "DR", "DT", "IA", "IP", "IR", "X", "OF", "OC", "DF", "DC", "DY" ] }, "oceanMilestoneEventCodeEnum": { "type": "string", "description": "Code that indicates the type of milestone being sent for a shipment being moved by boat. For a detailed description of all enumerated codes please find them here.", "enum": [ "2", "3", "A", "A1", "A2", "A3", "A4", "AA", "AC", "AD", "AE", "AF", "AG", "AH", "AI", "AJ", "AL", "AM", "AN", "AO", "AP", "AR", "AV", "AW", "B", "BA", "BC", "BD", "BE", "BF", "BR", "C", "C1", "C2", "CA", "CB", "CC", "CD", "CI", "CO", "CR", "CS", "CT", "CU", "CV", "D", "DA", "DC", "DN", "DP", "DR", "DS", "DT", "E", "EA", "ED", "EE", "EP", "ER", "F", "FP", "FT", "G", "GI", "GO", "H", "HA", "HE", "HF", "HG", "HH", "HI", "HR", "I", "IB", "IR", "J1", "K1", "L", "LD", "LP", "MT", "N", "NC", "ND", "NF", "NH", "NO", "NP", "NR", "NS", "NT", "NU", "O", "OA", "OB", "OF", "OH", "ON", "P", "PA", "PB", "PC", "PD", "PE", "PF", "PG", "PH", "PI", "PJ", "PK", "PL", "PM", "PN", "PO", "PP", "PQ", "PR", "PS", "PT", "PU", "PV", "PW", "PX", "R", "RA", "RB", "RC", "RD", "RI", "RL", "RN", "S", "SA", "SB", "SC", "SD", "T", "SI", "SN", "TC", "TM", "TO", "U", "UA", "UB", "UC", "UD", "UE", "UP", "UR", "UV", "UW", "V", "VA", "VD", "W", "WH", "WR", "X", "XA", "X1", "X2", "X3", "X4", "X5", "X6", "X7", "X9", "X8", "XB", "Y", "Z" ] }, "railDetail": { "type": "object", "description": "Identifies rail information.", "properties": { "sightingCode": { "type": "string", "description": "Rail specific event codes." }, "trainNumber": { "type": "string", "description": "Identifies the train the miletsone refers to." } } }, "railMilestoneEventCodeEnum": { "type": "string", "description": "Code that indicates the type of milestone being sent for a shipment being moved by train. For a detailed description of all enumerated codes please find them here.", "enum": [ "3", "6", "7", "9", "A", "B", "C", "D", "E", "F", "G", "I", "J", "K", "L", "M", "P", "Q", "R", "S", "U", "V", "W", "X", "Y", "Z" ] }, "roadMilestoneEventCodeEnum": { "type": "string", "description": "Code that indicates the type of milestone being sent for a shipment being moved by truck. For a detailed description of all enumerated codes please find them here.", "enum": [ "A3", "A7", "A9", "AA", "AB", "AC", "AF", "AG", "AH", "AI", "AJ", "AM", "AN", "AP", "AR", "AV", "B6", "BA", "BC", "C1", "CA", "CD", "CL", "CP", "D1", "ED", "EP", "I1", "J1", "K1", "L1", "LD", "LP", "OA", "OO", "P1", "PR", "R1", "RL", "S1", "SD", "XA", "X1", "X2", "X3", "X4", "X5", "X6", "X9", "X8", "XB" ] }, "shipmentIdentifier": { "type": "object", "description": "A list of different common reference numbers that can be used to identify the shipment the milestone is intended for. \n\n ### At least one ship identifier needs to be present.", "properties": { "shipmentNumber": { "type": "string", "minimum": 1, "maximum": 20, "description": "Defined ID for the shipment. Usually the C.H. Robinson load number." }, "shipperBillToId": { "type": "string", "minimum": 1, "maximum": 50, "description": "Shipper defined Bill To reference number for the shipment." }, "proNumber": { "type": "string", "minimum": 1, "maximum": 20, "description": "Carrier defined pro number for the shipment." }, "trackingNumber": { "type": "string", "minimum": 1, "maximum": 150, "description": "Carrier or customer defined tracking number for the shipment." }, "containerNumber": { "type": "string", "minimum": 1, "maximum": 20, "description": "Carrier or customer defined container number for the shipment." } } }, "stateProvinceCodeEnum": { "type": "string", "description": "Indicate the state or province of the location. \n\nFor a detailed description of all enumerated codes please find them here.", "enum": [ "1", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19", "2", "20", "21", "22", "23", "24", "25", "26", "27", "28", "29", "3", "30", "31", "32", "33", "34", "35", "36", "37", "38", "39", "4", "40", "41", "42", "43", "44", "45", "46", "47", "48", "49", "5", "50", "51", "52", "53", "54", "6", "61", "62", "63", "64", "65", "67", "7", "71", "76", "79", "8", "81", "84", "86", "89", "9", "91", "92", "95", "A", "AA", "AB", "AC", "AE", "AG", "AGU", "AI", "AK", "AL", "AM", "AN", "AO", "AP", "AQ", "AR", "AS", "AT", "AUK", "AV", "AZ", "B", "BA", "BC", "BCN", "BCS", "BG", "BI", "BL", "BM", "BN", "BO", "BOP", "BR", "BS", "BT", "BZ", "C", "CA", "CAM", "CAN", "CB", "CE", "CH", "CHH", "CHP", "CI", "CL", "CN", "CO", "COA", "COL", "CR", "CS", "CT", "CZ", "D", "DC", "DD", "DE", "DF", "DL", "DN", "DUR", "E", "EN", "ES", "F", "FC", "FE", "FG", "FI", "FL", "FM", "FR", "G", "GA", "GE", "GIS", "GJ", "GO", "GR", "GRO", "GU", "GUA", "H", "HI", "HID", "HKB", "HP", "HR", "IA", "ID", "IL", "IM", "IN", "IS", "J", "JAL", "JH", "JK", "K", "KA", "KL", "KR", "KS", "KY", "L", "LA", "LC", "LD", "LE", "LI", "LL", "LO", "LT", "LU", "M", "MA", "MB", "MBH", "MC", "MD", "ME", "MEX", "MG", "MH", "MI", "MIC", "ML", "MN", "MO", "MOR", "MP", "MS", "MT", "MWT", "MZ", "N", "NA", "NAY", "NB", "NC", "ND", "NE", "NH", "NJ", "NL", "NLE", "NM", "NO", "NS", "NSN", "NSW", "NT", "NTL", "NU", "NV", "NY", "O", "OAX", "OG", "OH", "OI", "OK", "ON", "OR", "OT", "OTA", "P", "PA", "PB", "PC", "PD", "PE", "PG", "PI", "PN", "PO", "PR", "PT", "PU", "PUE", "PV", "PY", "PZ", "Q", "QC", "QLD", "QU", "QUE", "R", "RA", "RC", "RE", "RG", "RI", "RJ", "RM", "RN", "RO", "ROO", "RR", "RS", "S", "SA", "SC", "SD", "SE", "SI", "SIN", "SJ", "SK", "SLP", "SO", "SON", "SP", "SR", "SS", "STL", "SV", "T", "TA", "TAB", "TAM", "TAS", "TE", "TG", "TKI", "TLA", "TN", "TO", "TP", "TR", "TS", "TV", "TX", "U", "UD", "UL", "UM", "UP", "UT", "V", "VA", "VB", "VC", "VE", "VER", "VI", "VIC", "VR", "VS", "VT", "VV", "W", "WA", "WB", "WGN", "WI", "WKO", "WTC", "WV", "WY", "X", "Y", "YT", "YUC", "Z", "ZAC" ] }, "supplementalInformation": { "type": "object", "description": "Allows updating entity to provide additional details pertaining to the milestone.", "properties": { "reasonCode": { "$ref": "#/$defs/lateCodeEnum" }, "notes": { "type": "string", "description": "Allows updating entity to provide any notations pertaining to the milestone." } } }, "temperatureUomEnum": { "type": "string", "description": "Unit of measure for temperature parameters.", "enum": [ "Fahrenheit", "Celsius", "Empty" ] }, "vehicleContact": { "type": "object", "description": "Contact information.", "properties": { "driverName": { "type": "string", "description": "Name of the driver associated to the milestone." }, "driverPhone": { "type": "string", "description": "Phone number of the driver associated to the milestone." }, "secondDriverName": { "type": "string", "description": "In instances of driver teams, name of the second driver associated to the milestone." }, "secondDriverPhone": { "type": "string", "description": "In instances of driver teams, phone number of the second driver associated to the milestone." }, "dispatchName": { "type": "string", "description": "Name of individual at carrier dispatch center." }, "dispatchPhone": { "type": "string", "description": "Phone number of carrier dispatcher." } } }, "vehicleDetail": { "type": "object", "description": "Identifies vehicle information.", "properties": { "tractorNumber": { "type": "string", "description": "Identifier of the powered unit transporting the shipment." }, "trailerNumber": { "type": "string", "description": "Identifier of the trailer the shipment resides in." }, "licensePlate": { "type": "string", "description": "License plate of the powered unit." }, "licensePlateState": { "type": "string", "description": "State the license plate was issued" }, "vin": { "type": "string", "description": "Vehicle idendification number of the powered unit." }, "contactInformation": { "$ref": "#/$defs/vehicleContact" } } }, "vesselDetail": { "type": "object", "description": "Identifies vessel information.", "properties": { "vesselName": { "type": "string", "description": "Identifies the name of the vessel." }, "voyageNumber": { "type": "string", "description": "Identifies the voyage number.." }, "vesselIMONumber": { "type": "string", "description": "Identifies vessel IMO number." }, "hullNumber": { "type": "string", "description": "Identifies the hull number of the vessel." } } }, "weightUomEnum": { "type": "string", "description": "Unit of measure for weight parameters.", "enum": [ "Pounds", "Kilograms" ] } } }