[{"data":1,"prerenderedAt":579},["ShallowReactive",2],{"changelog:off-route":3,"\u002Fshipments":4,"docs-nav":514},null,{"id":5,"title":6,"body":7,"cards":3,"description":501,"extension":502,"group":503,"hero":3,"icon":504,"meta":505,"navTitle":506,"navigation":507,"order":248,"path":508,"seo":509,"sitemap":510,"stem":512,"__hash__":513},"docs\u002Fshipments.md","Changing a shipment",{"type":8,"value":9,"toc":490},"minimark",[10,14,18,37,40,104,118,139,144,147,152,188,192,199,252,255,266,269,273,285,325,328,365,368,372,377,417,421,472,486],[11,12,6],"h1",{"id":13},"changing-a-shipment",[15,16,17],"p",{},"A shipment can be read in full, and two of its fields can be written:",[19,20,21,30],"ul",{},[22,23,24,25,29],"li",{},"the ",[26,27,28],"strong",{},"cargo-ready date",", the day your supplier has the cargo ready for\ncollection;",[22,31,32,33,36],{},"your ",[26,34,35],{},"client references",", your own order or purchase-order numbers.",[15,38,39],{},"Send the fields that change, and only those:",[41,42,48],"pre",{"className":43,"code":44,"filename":45,"language":46,"meta":47,"style":47},"language-bash shiki shiki-themes github-dark github-dark","curl -X PATCH 'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment\u002FC2AE-XEE1' \\\n  -H 'X-Cargoplot-Key: \u003Ctoken>' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{ \"cargo_ready_date\": \"2026-11-09\", \"client_references\": [\"S05749\"] }'\n","PATCH \u002Fv1\u002Fshipment\u002FC2AE-XEE1","bash","",[49,50,51,74,85,95],"code",{"__ignoreMap":47},[52,53,56,60,64,68,71],"span",{"class":54,"line":55},"line",1,[52,57,59],{"class":58},"sFR8T","curl",[52,61,63],{"class":62},"s8ozJ"," -X",[52,65,67],{"class":66},"s4wv1"," PATCH",[52,69,70],{"class":66}," 'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment\u002FC2AE-XEE1'",[52,72,73],{"class":62}," \\\n",[52,75,77,80,83],{"class":54,"line":76},2,[52,78,79],{"class":62},"  -H",[52,81,82],{"class":66}," 'X-Cargoplot-Key: \u003Ctoken>'",[52,84,73],{"class":62},[52,86,88,90,93],{"class":54,"line":87},3,[52,89,79],{"class":62},[52,91,92],{"class":66}," 'Content-Type: application\u002Fjson'",[52,94,73],{"class":62},[52,96,98,101],{"class":54,"line":97},4,[52,99,100],{"class":62},"  -d",[52,102,103],{"class":66}," '{ \"cargo_ready_date\": \"2026-11-09\", \"client_references\": [\"S05749\"] }'\n",[15,105,106,109,110,113,114,117],{},[49,107,108],{},"{shipment}"," takes the Cargoplot reference or the numeric id, as the reads do.\nThe answer is ",[49,111,112],{},"200"," with the whole shipment, exactly as\n",[49,115,116],{},"GET \u002Fv1\u002Fshipment\u002F{shipment}"," renders it.",[15,119,120,121,124,125,130,131,134,135,138],{},"Each field has its own lock, described below. A body that carries both is\nrefused whole when either is refused, so nothing changes. Sending a value the\nshipment already has is never refused, so repeating a request is harmless.\nEvery change is recorded in the shipment's history and moves the shipment's\n",[49,122,123],{},"update_time",", which is what\n",[126,127,129],"a",{"href":128},"\u002Fpagination#keeping-a-copy-in-sync","keeping a copy in sync"," reads. Any other key,\nthe shipment's other fields included, answers ",[49,132,133],{},"400"," and ",[49,136,137],{},"message"," names it.",[140,141,143],"h2",{"id":142},"the-cargo-ready-date","The cargo-ready date",[15,145,146],{},"When the day the cargo is ready moves, send the new one. The Cargoplot team\nhandling the shipment gets a task to follow the change up: moving the pickup,\nand whatever is booked around it, is theirs to arrange.",[148,149,151],"h3",{"id":150},"what-is-accepted","What is accepted",[19,153,154,171],{},[22,155,156,163,164,167,168,170],{},[26,157,158,159,162],{},"A calendar date, as ",[49,160,161],{},"YYYY-MM-DD","."," A day that does not exist, such as\n",[49,165,166],{},"2026-02-31",", answers ",[49,169,133],{},", and so does an empty value: the date cannot be\ncleared.",[22,172,173,176,177,179,180,183,184,162],{},[26,174,175],{},"Not before today, counted in UTC."," Around midnight your own today and the\nUTC one can differ by a day. A date in the past answers ",[49,178,133],{}," with a field\nviolation on ",[49,181,182],{},"cargo_ready_date",", as described under\n",[126,185,187],{"href":186},"\u002Ferrors#when-a-request-body-is-refused","errors",[148,189,191],{"id":190},"once-the-cargo-has-been-picked-up","Once the cargo has been picked up",[15,193,194,195,198],{},"From then on the date is history rather than a plan, and a change answers\n",[49,196,197],{},"409",":",[41,200,204],{"className":201,"code":202,"language":203,"meta":47,"style":47},"language-json shiki shiki-themes github-dark github-dark","{\n  \"code\": 10,\n  \"message\": \"the cargo has already been picked up, so its cargo-ready date can no longer be changed\",\n  \"details\": []\n}\n","json",[49,205,206,212,226,238,246],{"__ignoreMap":47},[52,207,208],{"class":54,"line":55},[52,209,211],{"class":210},"suv1-","{\n",[52,213,214,217,220,223],{"class":54,"line":76},[52,215,216],{"class":62},"  \"code\"",[52,218,219],{"class":210},": ",[52,221,222],{"class":62},"10",[52,224,225],{"class":210},",\n",[52,227,228,231,233,236],{"class":54,"line":87},[52,229,230],{"class":62},"  \"message\"",[52,232,219],{"class":210},[52,234,235],{"class":66},"\"the cargo has already been picked up, so its cargo-ready date can no longer be changed\"",[52,237,225],{"class":210},[52,239,240,243],{"class":54,"line":97},[52,241,242],{"class":62},"  \"details\"",[52,244,245],{"class":210},": []\n",[52,247,249],{"class":54,"line":248},5,[52,250,251],{"class":210},"}\n",[15,253,254],{},"Nothing records the pickup itself, so Cargoplot treats the cargo as picked up\nonce any of these holds:",[19,256,257,260,263],{},[22,258,259],{},"the shipment is completed or cancelled;",[22,261,262],{},"tracking reports the cargo loaded, sailing, arrived or discharged;",[22,264,265],{},"its ETD has come: the ETD's day, in UTC, is today or earlier.",[15,267,268],{},"If the date has to change after that, get in touch with your Cargoplot contact.\nThe app follows the same rules, so a colleague cannot move it there either.",[140,270,272],{"id":271},"client-references","Client references",[15,274,275,276,279,280,284],{},"Your own order or purchase-order numbers, such as ",[49,277,278],{},"S05749",", so you can link a\nshipment to your orders exactly. A shipment created from an inquiry starts with\nthe ",[126,281,283],{"href":282},"\u002Finquiries","inquiry's references","; from then on they are kept, and changed,\non the shipment.",[41,286,288],{"className":43,"code":287,"filename":45,"language":46,"meta":47,"style":47},"curl -X PATCH 'https:\u002F\u002Fapi.cargoplot.com\u002Fv1\u002Fshipment\u002FC2AE-XEE1' \\\n  -H 'X-Cargoplot-Key: \u003Ctoken>' \\\n  -H 'Content-Type: application\u002Fjson' \\\n  -d '{ \"client_references\": [\"S05749\", \"S05750\"] }'\n",[49,289,290,302,310,318],{"__ignoreMap":47},[52,291,292,294,296,298,300],{"class":54,"line":55},[52,293,59],{"class":58},[52,295,63],{"class":62},[52,297,67],{"class":66},[52,299,70],{"class":66},[52,301,73],{"class":62},[52,303,304,306,308],{"class":54,"line":76},[52,305,79],{"class":62},[52,307,82],{"class":66},[52,309,73],{"class":62},[52,311,312,314,316],{"class":54,"line":87},[52,313,79],{"class":62},[52,315,92],{"class":66},[52,317,73],{"class":62},[52,319,320,322],{"class":54,"line":97},[52,321,100],{"class":62},[52,323,324],{"class":66}," '{ \"client_references\": [\"S05749\", \"S05750\"] }'\n",[148,326,151],{"id":327},"what-is-accepted-1",[19,329,330,336,348],{},[22,331,332,335],{},[26,333,334],{},"The list replaces the stored one."," Send every reference the shipment\nshould have; an empty list clears them.",[22,337,338,341,342,344,345,162],{},[26,339,340],{},"At most 20 references, each 1 to 64 characters"," once surrounding\nwhitespace is trimmed, and none twice. A list that breaks a rule answers ",[49,343,133],{},"\nwith a field violation on ",[49,346,347],{},"client_references",[22,349,350,353,354,134,356,359,360,364],{},[26,351,352],{},"Stored as written",", case included. ",[49,355,278],{},[49,357,358],{},"s05749"," are different\nreferences, though a ",[126,361,363],{"href":362},"\u002Fpagination#filter-expressions","filter"," matches either.",[15,366,367],{},"No task is raised: a change of references is recorded in the shipment's\nhistory and needs nothing from the Cargoplot team.",[148,369,371],{"id":370},"once-the-shipment-is-completed-or-cancelled","Once the shipment is completed or cancelled",[15,373,374,375,198],{},"References can still be changed after the cargo has been picked up, but not\nonce the shipment is completed or cancelled. A change then answers ",[49,376,197],{},[41,378,380],{"className":201,"code":379,"language":203,"meta":47,"style":47},"{\n  \"code\": 10,\n  \"message\": \"the shipment is completed or cancelled, so its client references can no longer be changed\",\n  \"details\": []\n}\n",[49,381,382,386,396,407,413],{"__ignoreMap":47},[52,383,384],{"class":54,"line":55},[52,385,211],{"class":210},[52,387,388,390,392,394],{"class":54,"line":76},[52,389,216],{"class":62},[52,391,219],{"class":210},[52,393,222],{"class":62},[52,395,225],{"class":210},[52,397,398,400,402,405],{"class":54,"line":87},[52,399,230],{"class":62},[52,401,219],{"class":210},[52,403,404],{"class":66},"\"the shipment is completed or cancelled, so its client references can no longer be changed\"",[52,406,225],{"class":210},[52,408,409,411],{"class":54,"line":97},[52,410,242],{"class":62},[52,412,245],{"class":210},[52,414,415],{"class":54,"line":248},[52,416,251],{"class":210},[140,418,420],{"id":419},"when-a-change-is-refused","When a change is refused",[422,423,424,437],"table",{},[425,426,427],"thead",{},[428,429,430,434],"tr",{},[431,432,433],"th",{},"Status",[431,435,436],{},"Why",[438,439,440,453,463],"tbody",{},[428,441,442,447],{},[443,444,445],"td",{},[49,446,133],{},[443,448,449,450,452],{},"A value breaks a rule, the body has a key the request does not have, or it names no field at all (",[49,451,137],{},": \"the request body names no field to change\")",[428,454,455,460],{},[443,456,457],{},[49,458,459],{},"404",[443,461,462],{},"No shipment with that reference or id in your organization",[428,464,465,469],{},[443,466,467],{},[49,468,197],{},[443,470,471],{},"A field is locked: the cargo has been picked up, for the cargo-ready date, or the shipment is completed or cancelled, for the client references",[15,473,474,475,478,479,481,482,485],{},"A value that breaks a rule answers with a ",[49,476,477],{},"google.rpc.BadRequest"," naming the\nfield and why. An unknown key is named in ",[49,480,137],{}," instead. The\n",[126,483,187],{"href":484},"\u002Ferrors"," page shows both shapes in full and says which failures are\nworth retrying.",[487,488,489],"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":47,"searchDepth":76,"depth":76,"links":491},[492,496,500],{"id":142,"depth":76,"text":143,"children":493},[494,495],{"id":150,"depth":87,"text":151},{"id":190,"depth":87,"text":191},{"id":271,"depth":76,"text":272,"children":497},[498,499],{"id":327,"depth":87,"text":151},{"id":370,"depth":87,"text":371},{"id":419,"depth":76,"text":420},"Move the cargo-ready date until the cargo has been picked up, and keep your own order references on the shipment up to date.","md","working","mdi-truck-check-outline",{},"Shipments",true,"\u002Fshipments",{"title":6,"description":501},{"loc":508,"lastmod":511},"2026-11-11","shipments","w0Lgu6HX8p1sbhe1pASvGnDgFaAK_NYiO343smUoKaM",[515,520,524,529,533,538,539,544,549,554,559,564,568,573],{"path":516,"title":517,"navTitle":517,"icon":518,"group":519,"order":55},"\u002F","Overview","mdi-book-open-page-variant-outline","getting-started",{"path":521,"title":522,"navTitle":3,"icon":523,"group":519,"order":76},"\u002Fauthentication","Authentication","mdi-key-variant",{"path":525,"title":526,"navTitle":527,"icon":528,"group":519,"order":87},"\u002Fai-assistants","Connect an AI assistant","AI assistants","mdi-robot-outline",{"path":282,"title":530,"navTitle":531,"icon":532,"group":503,"order":97},"Creating and updating inquiries","Inquiries","mdi-file-document-edit-outline",{"path":534,"title":535,"navTitle":535,"icon":536,"group":503,"order":537},"\u002Fquotes","Quotes","mdi-tag-multiple-outline",4.5,{"path":508,"title":6,"navTitle":506,"icon":504,"group":503,"order":248},{"path":540,"title":541,"navTitle":541,"icon":542,"group":503,"order":543},"\u002Fdocuments","Documents","mdi-file-upload-outline",5.5,{"path":545,"title":546,"navTitle":546,"icon":547,"group":503,"order":548},"\u002Fmessages","Messages","mdi-message-text-outline",5.7,{"path":550,"title":551,"navTitle":3,"icon":552,"group":503,"order":553},"\u002Ftracking","Shipment tracking","mdi-map-marker-path",6,{"path":555,"title":556,"navTitle":3,"icon":557,"group":503,"order":558},"\u002Frate-limits","Rate limits","mdi-speedometer",7,{"path":560,"title":561,"navTitle":3,"icon":562,"group":503,"order":563},"\u002Fpagination","Pagination and filtering","mdi-filter-variant",8,{"path":484,"title":565,"navTitle":3,"icon":566,"group":503,"order":567},"Errors","mdi-alert-outline",9,{"path":569,"title":570,"navTitle":3,"icon":571,"group":503,"order":572},"\u002Fglossary","Glossary","mdi-book-alphabet",10,{"path":574,"title":575,"navTitle":3,"icon":576,"group":577,"order":578},"\u002Fversioning","Versioning","mdi-tag-outline","current",11,1794912850101]