[{"data":1,"prerenderedAt":923},["ShallowReactive",2],{"changelog:off-route":3,"\u002Ftracking":4,"docs-nav":893},null,{"id":5,"title":6,"body":7,"cards":3,"description":881,"extension":882,"group":883,"hero":3,"icon":884,"meta":885,"navTitle":3,"navigation":886,"order":163,"path":887,"seo":888,"sitemap":889,"stem":891,"__hash__":892},"docs\u002Ftracking.md","Shipment tracking",{"type":8,"value":9,"toc":870},"minimark",[10,14,23,31,80,90,95,130,134,401,404,408,415,638,645,661,666,675,679,689,698,706,719,723,760,767,771,784,802,805,809,833,850,866],[11,12,6],"h1",{"id":13},"shipment-tracking",[15,16,17,18,22],"p",{},"Use ",[19,20,21],"code",{},"GET \u002Fv1\u002Fshipment\u002F{shipment}\u002Ftracking"," to read a shipment's movement\ntimeline. The path accepts either the Cargoplot reference or the numeric\nshipment id.",[15,24,25,26,30],{},"Sea and air journeys are described differently, so the timeline is nested under\na key naming the shipment's transport mode. A response carries ",[27,28,29],"strong",{},"exactly one","\nof them, decided by the shipment itself.",[32,33,34,50],"table",{},[35,36,37],"thead",{},[38,39,40,44,47],"tr",{},[41,42,43],"th",{},"Key",[41,45,46],{},"Transport mode",[41,48,49],{},"Timeline",[51,52,53,67],"tbody",{},[38,54,55,61,64],{},[56,57,58],"td",{},[19,59,60],{},"sea",[56,62,63],{},"Sea freight",[56,65,66],{},"One entry per container, each with its own events",[38,68,69,74,77],{},[56,70,71],{},[19,72,73],{},"air",[56,75,76],{},"Air freight",[56,78,79],{},"One overall status and one list of events for the shipment",[15,81,82,85,86,89],{},[19,83,84],{},"etd"," and ",[19,87,88],{},"eta"," sit at the top level, beside the mode key, because they mean the\nsame thing whichever mode it is.",[91,92,94],"h2",{"id":93},"request","Request",[96,97,102],"pre",{"className":98,"code":99,"language":100,"meta":101,"style":101},"language-bash shiki shiki-themes github-dark github-dark","curl -H 'X-Cargoplot-Key: \u003Ctoken>' \\\n  'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment\u002FC2AE-XEE1\u002Ftracking'\n","bash","",[19,103,104,124],{"__ignoreMap":101},[105,106,109,113,117,121],"span",{"class":107,"line":108},"line",1,[105,110,112],{"class":111},"sFR8T","curl",[105,114,116],{"class":115},"s8ozJ"," -H",[105,118,120],{"class":119},"s4wv1"," 'X-Cargoplot-Key: \u003Ctoken>'",[105,122,123],{"class":115}," \\\n",[105,125,127],{"class":107,"line":126},2,[105,128,129],{"class":119},"  'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment\u002FC2AE-XEE1\u002Ftracking'\n",[91,131,133],{"id":132},"sea-response","Sea response",[96,135,139],{"className":136,"code":137,"language":138,"meta":101,"style":101},"language-json shiki shiki-themes github-dark github-dark","{\n  \"etd\": \"2026-09-05\",\n  \"eta\": \"2026-09-08\",\n  \"sea\": {\n    \"containers\": [\n      {\n        \"container_number\": \"MSKU1234567\",\n        \"container_type\": \"CONTAINER_TYPE_40_HIGH_CUBE\",\n        \"status\": \"CONTAINER_TRACKING_STATUS_SAILING\",\n        \"events\": [\n          {\n            \"type\": \"SEA_TRACKING_EVENT_TYPE_DEPARTED\",\n            \"state\": \"TRACKING_EVENT_STATE_ACTUAL\",\n            \"timestamp\": \"2026-09-05T10:00:00Z\",\n            \"location\": {\n              \"un_locode\": \"SGSIN\",\n              \"name\": \"Singapore\"\n            },\n            \"vessel\": {\n              \"name\": \"Example Vessel\",\n              \"voyage\": \"001W\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n","json",[19,140,141,147,161,174,183,192,198,211,224,237,245,251,264,277,290,298,311,322,328,336,348,359,365,371,377,383,389,395],{"__ignoreMap":101},[105,142,143],{"class":107,"line":108},[105,144,146],{"class":145},"suv1-","{\n",[105,148,149,152,155,158],{"class":107,"line":126},[105,150,151],{"class":115},"  \"etd\"",[105,153,154],{"class":145},": ",[105,156,157],{"class":119},"\"2026-09-05\"",[105,159,160],{"class":145},",\n",[105,162,164,167,169,172],{"class":107,"line":163},3,[105,165,166],{"class":115},"  \"eta\"",[105,168,154],{"class":145},[105,170,171],{"class":119},"\"2026-09-08\"",[105,173,160],{"class":145},[105,175,177,180],{"class":107,"line":176},4,[105,178,179],{"class":115},"  \"sea\"",[105,181,182],{"class":145},": {\n",[105,184,186,189],{"class":107,"line":185},5,[105,187,188],{"class":115},"    \"containers\"",[105,190,191],{"class":145},": [\n",[105,193,195],{"class":107,"line":194},6,[105,196,197],{"class":145},"      {\n",[105,199,201,204,206,209],{"class":107,"line":200},7,[105,202,203],{"class":115},"        \"container_number\"",[105,205,154],{"class":145},[105,207,208],{"class":119},"\"MSKU1234567\"",[105,210,160],{"class":145},[105,212,214,217,219,222],{"class":107,"line":213},8,[105,215,216],{"class":115},"        \"container_type\"",[105,218,154],{"class":145},[105,220,221],{"class":119},"\"CONTAINER_TYPE_40_HIGH_CUBE\"",[105,223,160],{"class":145},[105,225,227,230,232,235],{"class":107,"line":226},9,[105,228,229],{"class":115},"        \"status\"",[105,231,154],{"class":145},[105,233,234],{"class":119},"\"CONTAINER_TRACKING_STATUS_SAILING\"",[105,236,160],{"class":145},[105,238,240,243],{"class":107,"line":239},10,[105,241,242],{"class":115},"        \"events\"",[105,244,191],{"class":145},[105,246,248],{"class":107,"line":247},11,[105,249,250],{"class":145},"          {\n",[105,252,254,257,259,262],{"class":107,"line":253},12,[105,255,256],{"class":115},"            \"type\"",[105,258,154],{"class":145},[105,260,261],{"class":119},"\"SEA_TRACKING_EVENT_TYPE_DEPARTED\"",[105,263,160],{"class":145},[105,265,267,270,272,275],{"class":107,"line":266},13,[105,268,269],{"class":115},"            \"state\"",[105,271,154],{"class":145},[105,273,274],{"class":119},"\"TRACKING_EVENT_STATE_ACTUAL\"",[105,276,160],{"class":145},[105,278,280,283,285,288],{"class":107,"line":279},14,[105,281,282],{"class":115},"            \"timestamp\"",[105,284,154],{"class":145},[105,286,287],{"class":119},"\"2026-09-05T10:00:00Z\"",[105,289,160],{"class":145},[105,291,293,296],{"class":107,"line":292},15,[105,294,295],{"class":115},"            \"location\"",[105,297,182],{"class":145},[105,299,301,304,306,309],{"class":107,"line":300},16,[105,302,303],{"class":115},"              \"un_locode\"",[105,305,154],{"class":145},[105,307,308],{"class":119},"\"SGSIN\"",[105,310,160],{"class":145},[105,312,314,317,319],{"class":107,"line":313},17,[105,315,316],{"class":115},"              \"name\"",[105,318,154],{"class":145},[105,320,321],{"class":119},"\"Singapore\"\n",[105,323,325],{"class":107,"line":324},18,[105,326,327],{"class":145},"            },\n",[105,329,331,334],{"class":107,"line":330},19,[105,332,333],{"class":115},"            \"vessel\"",[105,335,182],{"class":145},[105,337,339,341,343,346],{"class":107,"line":338},20,[105,340,316],{"class":115},[105,342,154],{"class":145},[105,344,345],{"class":119},"\"Example Vessel\"",[105,347,160],{"class":145},[105,349,351,354,356],{"class":107,"line":350},21,[105,352,353],{"class":115},"              \"voyage\"",[105,355,154],{"class":145},[105,357,358],{"class":119},"\"001W\"\n",[105,360,362],{"class":107,"line":361},22,[105,363,364],{"class":145},"            }\n",[105,366,368],{"class":107,"line":367},23,[105,369,370],{"class":145},"          }\n",[105,372,374],{"class":107,"line":373},24,[105,375,376],{"class":145},"        ]\n",[105,378,380],{"class":107,"line":379},25,[105,381,382],{"class":145},"      }\n",[105,384,386],{"class":107,"line":385},26,[105,387,388],{"class":145},"    ]\n",[105,390,392],{"class":107,"line":391},27,[105,393,394],{"class":145},"  }\n",[105,396,398],{"class":107,"line":397},28,[105,399,400],{"class":145},"}\n",[15,402,403],{},"A sea event names its seaport by UN\u002FLOCODE, and carries the vessel and voyage\nwhere they are known.",[91,405,407],{"id":406},"air-response","Air response",[15,409,410,411,414],{},"Air cargo has no container to hang milestones on, so an air timeline sits at the\nshipment level: one ",[19,412,413],{},"status"," for the whole consignment, and one list of events.",[96,416,418],{"className":136,"code":417,"language":138,"meta":101,"style":101},"{\n  \"etd\": \"2026-09-05\",\n  \"eta\": \"2026-09-08\",\n  \"air\": {\n    \"status\": \"AIR_TRACKING_STATUS_IN_TRANSIT\",\n    \"events\": [\n      {\n        \"type\": \"AIR_TRACKING_EVENT_TYPE_DEPARTED\",\n        \"state\": \"TRACKING_EVENT_STATE_ACTUAL\",\n        \"timestamp\": \"2026-09-05T11:00:00Z\",\n        \"location\": {\n          \"iata\": \"SIN\",\n          \"name\": \"Singapore Changi\"\n        },\n        \"flight\": {\n          \"number\": \"KL0887\",\n          \"airline\": \"KLM\"\n        },\n        \"cargo\": {\n          \"pieces\": 3,\n          \"weight_kg\": 412.5,\n          \"volume_cbm\": 1.75\n        }\n      }\n    ]\n  }\n}\n",[19,419,420,424,434,444,451,463,470,474,486,497,509,516,528,538,543,550,562,572,576,583,595,607,617,622,626,630,634],{"__ignoreMap":101},[105,421,422],{"class":107,"line":108},[105,423,146],{"class":145},[105,425,426,428,430,432],{"class":107,"line":126},[105,427,151],{"class":115},[105,429,154],{"class":145},[105,431,157],{"class":119},[105,433,160],{"class":145},[105,435,436,438,440,442],{"class":107,"line":163},[105,437,166],{"class":115},[105,439,154],{"class":145},[105,441,171],{"class":119},[105,443,160],{"class":145},[105,445,446,449],{"class":107,"line":176},[105,447,448],{"class":115},"  \"air\"",[105,450,182],{"class":145},[105,452,453,456,458,461],{"class":107,"line":185},[105,454,455],{"class":115},"    \"status\"",[105,457,154],{"class":145},[105,459,460],{"class":119},"\"AIR_TRACKING_STATUS_IN_TRANSIT\"",[105,462,160],{"class":145},[105,464,465,468],{"class":107,"line":194},[105,466,467],{"class":115},"    \"events\"",[105,469,191],{"class":145},[105,471,472],{"class":107,"line":200},[105,473,197],{"class":145},[105,475,476,479,481,484],{"class":107,"line":213},[105,477,478],{"class":115},"        \"type\"",[105,480,154],{"class":145},[105,482,483],{"class":119},"\"AIR_TRACKING_EVENT_TYPE_DEPARTED\"",[105,485,160],{"class":145},[105,487,488,491,493,495],{"class":107,"line":226},[105,489,490],{"class":115},"        \"state\"",[105,492,154],{"class":145},[105,494,274],{"class":119},[105,496,160],{"class":145},[105,498,499,502,504,507],{"class":107,"line":239},[105,500,501],{"class":115},"        \"timestamp\"",[105,503,154],{"class":145},[105,505,506],{"class":119},"\"2026-09-05T11:00:00Z\"",[105,508,160],{"class":145},[105,510,511,514],{"class":107,"line":247},[105,512,513],{"class":115},"        \"location\"",[105,515,182],{"class":145},[105,517,518,521,523,526],{"class":107,"line":253},[105,519,520],{"class":115},"          \"iata\"",[105,522,154],{"class":145},[105,524,525],{"class":119},"\"SIN\"",[105,527,160],{"class":145},[105,529,530,533,535],{"class":107,"line":266},[105,531,532],{"class":115},"          \"name\"",[105,534,154],{"class":145},[105,536,537],{"class":119},"\"Singapore Changi\"\n",[105,539,540],{"class":107,"line":279},[105,541,542],{"class":145},"        },\n",[105,544,545,548],{"class":107,"line":292},[105,546,547],{"class":115},"        \"flight\"",[105,549,182],{"class":145},[105,551,552,555,557,560],{"class":107,"line":300},[105,553,554],{"class":115},"          \"number\"",[105,556,154],{"class":145},[105,558,559],{"class":119},"\"KL0887\"",[105,561,160],{"class":145},[105,563,564,567,569],{"class":107,"line":313},[105,565,566],{"class":115},"          \"airline\"",[105,568,154],{"class":145},[105,570,571],{"class":119},"\"KLM\"\n",[105,573,574],{"class":107,"line":324},[105,575,542],{"class":145},[105,577,578,581],{"class":107,"line":330},[105,579,580],{"class":115},"        \"cargo\"",[105,582,182],{"class":145},[105,584,585,588,590,593],{"class":107,"line":338},[105,586,587],{"class":115},"          \"pieces\"",[105,589,154],{"class":145},[105,591,592],{"class":115},"3",[105,594,160],{"class":145},[105,596,597,600,602,605],{"class":107,"line":350},[105,598,599],{"class":115},"          \"weight_kg\"",[105,601,154],{"class":145},[105,603,604],{"class":115},"412.5",[105,606,160],{"class":145},[105,608,609,612,614],{"class":107,"line":361},[105,610,611],{"class":115},"          \"volume_cbm\"",[105,613,154],{"class":145},[105,615,616],{"class":115},"1.75\n",[105,618,619],{"class":107,"line":367},[105,620,621],{"class":145},"        }\n",[105,623,624],{"class":107,"line":373},[105,625,382],{"class":145},[105,627,628],{"class":107,"line":379},[105,629,388],{"class":145},[105,631,632],{"class":107,"line":385},[105,633,394],{"class":145},[105,635,636],{"class":107,"line":391},[105,637,400],{"class":145},[15,639,640,641,644],{},"An air event names its airport by IATA code and carries the flight it happened on. Milestones that did not happen in the air — the handover from the shipper, and the final delivery — carry no ",[19,642,643],{},"flight"," at all.",[15,646,647,650,651,653,654,657,658,660],{},[19,648,649],{},"airline"," is the carrier on the waybill, and is itself optional — an event can\ncarry a ",[19,652,643],{}," with a ",[19,655,656],{},"number"," and no ",[19,659,649],{},". Where a consignment flew\npartly with another carrier, every event still names the same one, so read it as\nthe shipment's airline rather than the leg's.",[662,663,665],"h3",{"id":664},"air-status","Air status",[15,667,668,671,672,674],{},[19,669,670],{},"air.status"," describes the consignment as a whole. Unlike a container's\n",[19,673,413],{},", it is not derived from the event list, so it can say more than the\nevents do.",[662,676,678],{"id":677},"cargo-figures-and-when-they-are-absent","Cargo figures, and when they are absent",[15,680,681,684,685,688],{},[19,682,683],{},"cargo"," says how much of the consignment a milestone covered, which is what\ntells the legs of a split movement apart when two of them would otherwise look\nidentical. Each measure names its unit, and a measure that was not reported is\nabsent rather than ",[19,686,687],{},"0",".",[15,690,691,693,694,697],{},[19,692,683],{}," is omitted entirely when ",[27,695,696],{},"more than one of your shipments shares the same air waybill"," —\nthe figures on a shared waybill cover everything on it rather than your consignment alone.",[15,699,700,701,705],{},"The milestones keep the same flight facts — the aircraft's movements are the\nsame for every consignment on board. One consequence to know about, though: two\nlegs that differ ",[702,703,704],"em",{},"only"," in their cargo figures become indistinguishable once\nthose figures are gone, and are returned as a single milestone rather than two\nidentical ones. So on a shared waybill you cannot tell the legs of a split\nmovement apart, and the event list can be shorter than the number of legs\nflown.",[15,707,708,709,711,712,715,716,718],{},"On a consolidated master air waybill where yours is the only consignment booked through Cargoplot, ",[19,710,683],{}," ",[27,713,714],{},"is","\nreturned, and its figures still describe the whole waybill — including goods\nbelonging to parties we have no record of. Treat ",[19,717,683],{}," as \"how much moved on\nthis milestone\", not \"how much of mine moved\", unless you know the waybill\ncarries your consignment alone.",[91,720,722],{"id":721},"the-vocabularies","The vocabularies",[15,724,725,726,729,730,160,733,729,736,739,740,743,744,749,750,729,753,85,756,759],{},"Every value of ",[19,727,728],{},"SEA_TRACKING_EVENT_TYPE_*",", ",[19,731,732],{},"AIR_TRACKING_EVENT_TYPE_*",[19,734,735],{},"CONTAINER_TRACKING_STATUS_*",[19,737,738],{},"AIR_TRACKING_STATUS_*"," and\n",[19,741,742],{},"TRACKING_EVENT_STATE_*"," is listed with its meaning in the\n",[745,746,748],"a",{"href":747},"\u002Fglossary#tracking-milestones-and-statuses","glossary",", along with the\nfour-letter carrier codes such as ",[19,751,752],{},"GTIN",[19,754,755],{},"DEPA",[19,757,758],{},"DISC"," that the same\nmilestones carry in carrier portals and EDI messages. This endpoint returns the\nreadable names, never those codes.",[15,761,762,763,688],{},"Departure and arrival appear in both the sea and the air vocabulary. The two sets\nare separate, so a switch over one is unaffected as the other grows — but either\ncan gain a member, so handle an unrecognised value rather than assuming your\nswitch is exhaustive. See ",[745,764,766],{"href":765},"\u002Fversioning","versioning",[91,768,770],{"id":769},"fields-and-formats","Fields and formats",[15,772,773,729,775,85,777,780,781,783],{},[19,774,84],{},[19,776,88],{},[19,778,779],{},"discharge_date"," are ISO 8601 calendar dates — ",[19,782,157],{},". A date that is not known is absent from the response rather than\npresent and empty. Event, gate-out and empty-return timestamps are instants, so\nthey carry a time and use RFC 3339.",[15,785,786,787,790,791,794,795,798,799,801],{},"Events are ordered from oldest to newest. ",[19,788,789],{},"state"," tells you whether an event is\n",[19,792,793],{},"TRACKING_EVENT_STATE_EXPECTED"," or ",[19,796,797],{},"TRACKING_EVENT_STATE_ACTUAL",". A container's\n",[19,800,413],{}," follows its latest actual event, so an expected event does not move the\ncurrent status forward.",[15,803,804],{},"Location, vessel, voyage, flight, cargo, discharge, gate-out and empty-return\ndetails are included when known. Treat absent optional fields as unknown.",[91,806,808],{"id":807},"when-tracking-is-not-available-yet","When tracking is not available yet",[15,810,811,812,815,816,819,820,823,824,827,828,85,830,832],{},"A shipment answers with its mode key even before any movement data exists. On\nsea, a known container stays in ",[19,813,814],{},"containers"," with ",[19,817,818],{},"events: []","; on air, ",[19,821,822],{},"events","\nis ",[19,825,826],{},"[]",". An empty event list is a valid response, not a reason to discard the\nshipment, and ",[19,829,84],{},[19,831,88],{}," are still returned.",[15,834,835,836,838,839,842,843,846,847,849],{},"Do not branch on a particular ",[19,837,670],{}," to detect \"nothing yet\". An empty\nevent list can accompany either ",[19,840,841],{},"AIR_TRACKING_STATUS_UNSPECIFIED"," or\n",[19,844,845],{},"AIR_TRACKING_STATUS_AWAITING_AIRLINE_DATA"," — the latter is the ordinary\npre-departure case. Test ",[19,848,822],{}," for emptiness instead.",[15,851,852,853,856,857,860,861,865],{},"The endpoint returns ",[19,854,855],{},"400"," when the shipment is transported by road, rail or\nexpress, and ",[19,858,859],{},"404"," when no matching shipment is visible to your account. See\n",[745,862,864],{"href":863},"\u002Ferrors","errors"," for the common error response shapes.",[867,868,869],"style",{},"html pre.shiki code .sFR8T, html code.shiki .sFR8T{--shiki-default:#B392F0;--shiki-dark:#B392F0}html pre.shiki code .s8ozJ, html code.shiki .s8ozJ{--shiki-default:#79B8FF;--shiki-dark:#79B8FF}html pre.shiki code .s4wv1, html code.shiki .s4wv1{--shiki-default:#9ECBFF;--shiki-dark:#9ECBFF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .suv1-, html code.shiki .suv1-{--shiki-default:#E1E4E8;--shiki-dark:#E1E4E8}",{"title":101,"searchDepth":126,"depth":126,"links":871},[872,873,874,878,879,880],{"id":93,"depth":126,"text":94},{"id":132,"depth":126,"text":133},{"id":406,"depth":126,"text":407,"children":875},[876,877],{"id":664,"depth":163,"text":665},{"id":677,"depth":163,"text":678},{"id":721,"depth":126,"text":722},{"id":769,"depth":126,"text":770},{"id":807,"depth":126,"text":808},"Read the movement timeline for a sea or air shipment.","md","working","mdi-map-marker-path",{},true,"\u002Ftracking",{"title":6,"description":881},{"loc":887,"lastmod":890},"2026-09-12","tracking","GPZzYg4Qx-UNLhKUrsTcZNwe4FpeuIyNOOZz0C4Narc",[894,899,903,904,908,912,915,919],{"path":895,"title":896,"navTitle":896,"icon":897,"group":898,"order":108},"\u002F","Overview","mdi-book-open-page-variant-outline","getting-started",{"path":900,"title":901,"navTitle":3,"icon":902,"group":898,"order":126},"\u002Fauthentication","Authentication","mdi-key-variant",{"path":887,"title":6,"navTitle":3,"icon":884,"group":883,"order":163},{"path":905,"title":906,"navTitle":3,"icon":907,"group":883,"order":176},"\u002Frate-limits","Rate limits","mdi-speedometer",{"path":909,"title":910,"navTitle":3,"icon":911,"group":883,"order":185},"\u002Fpagination","Pagination and filtering","mdi-filter-variant",{"path":863,"title":913,"navTitle":3,"icon":914,"group":883,"order":194},"Errors","mdi-alert-outline",{"path":916,"title":917,"navTitle":3,"icon":918,"group":883,"order":200},"\u002Fglossary","Glossary","mdi-book-alphabet",{"path":765,"title":920,"navTitle":3,"icon":921,"group":922,"order":213},"Versioning","mdi-tag-outline","current",1789636124841]