1. Trans.eu Api
  2. Freights section
  3. Update freight

Update freight

Updat­ing exist­ing freight.
Updates are pos­si­ble only to freights that have not yet been pub­lished. Dur­ing the update, you can pub­lish freight at the same time.
With­out pub­li­ca­tion, only the freight fields describ­ing the load and vehi­cle para­me­ters can be updat­ed, the fields relat­ing to pub­li­ca­tion para­me­ters can­not be updat­ed.
Updat­ing exist­ing freights over­writes com­plete­ly freight. If any val­ue is not set and allowed as null, it will be con­sid­ered as null val­ue and over­writ­ten.
Freight can be updat­ed (also with the option of pub­lish­ing) with a request oth­er than the one it was cre­at­ed with.
If a freight has been added using automa­tion rules (with­out pub­lish), you can­not pub­lish that freight by updat­ing it.


The freight-id iden­ti­fi­ca­tion num­ber in method call can be tak­en from response after pre­vi­ous­ly cre­at­ing the freight or by down­load­ing the freight list.

PUT
/ext/freights-api/v1/freights/{freight-id}
PUT
/ext/freights-api/v1/freight-exchange/{freight-id}
PUT
/ext/freights-api/v1/private-exchange/{freight-id}
PUT
/ext/freights-api/v1/freight-corporate/{freight-id}
PUT
/ext/freights-api/v1/freight-companies/{freight-id}
PUT
/ext/freights-api/v1/freight-employees/{freight-id}
PUT
/ext/freights-api/v1/freight-auto/{freight-id}
Request Authorization

Every request MUST include a valid access token obtained dur­ing the user autho­riza­tion process, pro­vid­ed using the Bear­er token scheme in the Autho­riza­tion head­er.

Request

Request Head­er

Request Para­me­ters

Request Body

Successful Response

Response Fields

Response Body

Error Response

Client errors (400)

Gen­er­al API errors

Request Header (example)
PUT /ext/freights-api/v1/freight-exchange/{freight-id} HTTP/1.1 
Host: api.platform.trans.eu 
Content-Type: application/json
Accept: application/json
Authorization: Bearer {access_token) 
Api-key: {unique_app_api-key}
Request Parameters
AttributeTypeExam­pleManda­to­ryDescrip­tion
callback_urlStringhttp://example.com/msgNoThe return address pro­vid­ed by the client to receive freight and pub­li­ca­tion event sta­tus­es. See list of avail­able event sta­tus­es.
capac­i­tyFloat24YesTotal freight capac­i­ty in tonnes. This val­ue is being val­i­dat­ed in com­par­i­son to the sum of all loads weight
(range: 0,001 – 100000)
car­ri­ersArray of ObjectDescrip­tion of the object in Pub­lish to select­ed part­nersNoA list of carrier’s com­pa­ny iden­ti­fiers (at least one of com­pa­ny id’s must be valid).
Updat­ing this field is only pos­si­ble with the publish=true option and /ext/freights-api/v1/freight-companies/{freight-id} request.
contact_employeesArray of String[“13443–1”,“13443–2”]NoThe default con­tact per­son is always the pub­lish­er. If the field is sent, the con­tact per­sons will be only the ID’s sent in it.
Updat­ing this field is only pos­si­ble with the publish=true option.
decision_dateTime­stamp2025–08–03T13:00:00+0000NoDefines time up to which car­ri­ers can send offers. Cal­cu­lat­ed auto­mat­i­cal­ly for freight-exchange pub­li­ca­tion — it can be max 23:00 on the day of unload­ing.
Required con­di­tion: decision_date > publish_date.
Updat­ing this field is only pos­si­ble with the publish=true option.
employ­eesArray of String[“13452–1”,“28443–2”]NoList of users to whom the pub­li­ca­tion is addressed. The pub­li­ca­tion will only be effec­tive for users on the pub­lish­er’s Mes­sen­ger con­tact list.
Updat­ing this field is only pos­si­ble with the publish=true option and /ext/freights-api/v1/freight-employees/{freight-id} request.
exchangesObjectDescrip­tion of the object in Pub­lish to pri­vate exchanges or Pub­lish to brand­ed pri­vate exchangesNoCon­tain­er with pri­vate exchange ids.
Updat­ing this field is only pos­si­ble with the publish=true option and /ext/freights-api/v1/freight-corporate/{freight-id} or /ext/freights-api/v1/private-exchange/{freight-id} request.
heightInt or Float3.2NoExpected/required vehi­cle height (range: 0.01–10)
is_first_buyBooleanFalseNoDefines if price can be nego­ti­at­ed or only accept­ed by car­ri­er.
Updat­ing this field is only pos­si­ble with the publish=true option (but not with /ext/freights-api/v1/freight-exchange/{freight-id} request).
lengthInt or Float5NoExpected/required vehi­cle length (range: 0.01–100)
loading_metersFloat13.6NoTotal freight load­ing meters (range: 0,01 — 417)
loads (see details)Array of ObjectsNoCol­lec­tion of freight loads. It is pos­si­ble to send emp­ty array of loads, nev­er­the­less an array has to be set
pay­ment (see details)ObjectNoPay­ment con­di­tions for pub­li­ca­tion.
Updat­ing this field is only pos­si­ble with the publish=true option
pub­lishBooleanTrueYesDeter­mines if the freight is auto­mat­i­cal­ly pub­lished (True) or only updat­ed (False)
publish_dateTime­stamp2025–08–03T13:00:00+0000NoPub­li­ca­tion (acti­va­tion) date — must be greater or equal today, NULL — imme­di­ate pub­li­ca­tion.
Updat­ing this field is only pos­si­ble with the publish=true option.
require­ments (see details)ObjectYesMain freight require­ments.
send_order_proposal_
auto­mat­i­cal­ly		BooleanFalseNoSends the order con­di­tions auto­mat­i­cal­ly. This means that when the car­ri­er accepts such freight, an order is cre­at­ed with the terms of the order, and the ship­per does not have to com­plete them man­u­al­ly.
Updat­ing this field is only pos­si­ble with the publish=true option.
shipment_external_idString2023/NWX/1/3NoExter­nal iden­ti­fi­ca­tion num­ber
spots (see details)Array of ObjectsYesCol­lec­tion of freights’ spots – at least one load­ing and one unload­ing is required
transit_timeInt or Float280NoTime expressed in min­utes (pos­i­tive inte­ger) for trans­port. Must be less than the dif­fer­ence between the last unload­ing and the first load­ing.
vol­umeInt or Float21NoExpected/required vehi­cle vol­ume (range: 0.01–10000)
widthInt or Float3.1NoExpected/required vehi­cle width (range: 0.01–10)
Example Request Body
// Example request for PUT /ext/freights-api/v1/freight-exchange/3830568
{
  "callback_url": "http://example.com/msg",  
  "capacity": 12,
  "loads": [ {
      "type_of_load": "europalette",
      "name": "Load nr 1",
      "load_id": "1123dfd121_1",
      "amount":2,
      "is_exchangeable": true
  }],
  "payment": {
    "price": {
        "value": 552,
        "currency": "eur",
        "period": { 
            "payment": "deferred", 
            "days": 21
        }
    }
  },
  "publish": true,
  "publish_date": null,
  "requirements": {
    "is_ftl": true,
    "required_truck_bodies": [
      "box"
    ],
    "required_ways_of_loading": [ 
        "side" 
    ],
    "vehicle_size": "solo"
  },
  "send_order_proposal_automatically": true,
  "shipment_external_id": "1123dfd121",
  "spots": [
    {
      "spot_order": 1,
      "operations": [
        {
          "operation_order": 1,
          "type": "loading",
          "timespans": {
            "begin": "2026-02-23T16:30:58+01:00",
            "end": "2026-02-23T17:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "PL",
          "postal_code": "54-128",
          "locality": "Wroclaw"
        }
      }
    },
    {
      "spot_order": 2,
      "operations": [
        {
          "operation_order": 1,
          "type": "unloading",
          "timespans": {
            "begin": "2026-02-26T17:30:58+01:00",
            "end": "2026-02-26T18:30:58+01:00"
          }
        }
      ],
      "place": {
        "address": {
          "country": "IT",
          "postal_code": "20097",
          "locality": "Milan"
        }
      }
    }
  ]
}
Response Fields
AttributeTypeExam­pleDescrip­tion
accepted_priceObjectnullFinal price for freight accept­ed dur­ing pub­li­ca­tion and nego­ti­a­tion process. The val­ue is always null in this request.
capac­i­tyFloat22.1Total freight capac­i­ty in tonnes.
car­ri­erObjectnullCar­ri­er select­ed dur­ing nego­ti­a­tion process. The val­ue is always null in this request.
contact_employeesArray of ObjectsList of employ­ees assigned to freight nego­ti­a­tion. Default is pub­lish­er.
contact_employees.last_nameStringNowakSur­name of assigned employ­ee
contact_employees.nameStringJanFirst name of assigned employ­ee
contact_employees.trans_idString13443–1Tran­sId of assigned employ­ee
dis­tanceInt34000Dis­tance in meters from the point of load­ing to the point of unload­ing.
end_reasonStringnullPub­li­ca­tion end rea­son.
For cor­rect pub­li­ca­tion or freight cre­ation only null is returned.
heightFloat3.1Vehi­cle height (range: 0.01–10)
idInt234923Freight iden­ti­fi­ca­tion num­ber, assigned auto­mat­i­cal­ly dur­ing cre­ation of a new freight.
is_first_buyBooleanFalseDefines if price can be nego­ti­at­ed or only accept­ed by car­ri­er.
lengthFloat12Vehi­cle length (range: 0.01–100)
loading_metersFloat23Total freight load­ing meters (range: 0,01 — 417)
loads (see details)Array of ObjectsCol­lec­tion of freight loads.
publication_priceObjectPub­li­ca­tion price infor­ma­tion
publication_price.currencyStringeurPub­li­ca­tion price cur­ren­cy. See cur­ren­cy dic­tio­nary.
publication_price.valueInt560Pub­li­ca­tion price val­ue. The val­ue is null if was not spec­i­fied.
publication_receiversArray of String[“13452–1”,“28443–2”]List of users to whom the pub­li­ca­tion is addressed.
Field appears only for update with the publish=true option and /ext/freights-api/v1/freight-employees/{freight-id} request.
publication_statusStringnewSta­tus of the pub­li­ca­tion. The val­ue is always null in this request.
reference_numberStringFR/2025/12/30/2NNQFreight ref­er­ence num­ber — a unique, auto­mat­i­cal­ly assigned busi­ness iden­ti­fi­er of the freight
require­ments (see details)ObjectMain freight require­ments
shipment_external_idString2023/NWX/1/3Exter­nal iden­ti­fi­ca­tion num­ber
spots (see details)Array of ObjectsCol­lec­tion of freights’ spots. At least one load­ing and one unload­ing will occur.
sta­tusStringnewFreight sta­tus. The val­ue is always new in this request. See for oth­er pos­si­ble sta­tus­es.
sur­chagesObjectnullSur­chages for fixed routes. Always null in this request.
transit_timeInt460Time expressed in min­utes (pos­i­tive inte­ger) for trans­port, if spec­i­fied.
vol­umeFloat21Vehi­cle vol­ume (range 0.01–10000).
widthFloat3.1Vehi­cle width (range 0.01–10).
Response Body
// Example response for for PUT /ext/freights-api/v1/freight-exchange/3830568
{
    "accepted_price": null,
    "capacity": 12,
    "carrier": null,
    "contact_employees": [
        {
            "last_name": "Demczyszak",
            "name": "Barbara",
            "trans_id": "1007374-1"
        }
    ],
    "distance": 1185000,
    "end_reason": null,
    "height": null,
    "id": 3830568,
    "is_first_buy": false,
    "length": null,
    "loading_meters": null,
    "loads": [
        {
            "amount": 2,
            "description": null,
            "height": null,
            "id": 3766404,
            "is_exchangeable": true,
            "is_stackable": false,
            "length": null,
            "load_id": "3766404",
            "name": "Load nr 1",
            "type_of_load": "europalette",
            "volume": null,
            "weight": null,
            "width": null
        }
    ],
    "publication_price": {
        "currency": "eur",
        "value": 552
    },
    "publication_status": null,
    "reference_number": "FR/2026/02/23/221K",
    "requirements": {
        "exemption_from_adr": false,
        "is_ftl": true,
        "monitoring": "required",
        "other_requirements": [],
        "required_adr_classes": [],
        "required_door_types": [],
        "required_tipper_trailer_additional_equipment": [],
        "required_truck_bodies": [
            "box"
        ],
        "required_ways_of_loading": [
            "side"
        ],
        "shipping_remarks": null,
        "temperature": {
            "max": null,
            "min": null
        },
        "transport": {
            "count": null,
            "schedule_type": null,
            "settlement": "route",
            "settlement_basis": null,
            "total_weight": null,
            "type": "ftl"
        },
        "vehicle_size": "solo"
    },
    "shipment_external_id": "1123dfd121",
    "spots": [
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "3766404",
                            "weight": null
                        }
                    ],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-23T16:30:58+01:00",
                        "begin_local": "2026-02-23T16:30:58+01:00",
                        "end": "2026-02-23T17:30:58+01:00",
                        "end_local": "2026-02-23T17:30:58+01:00",
                        "timezone": "Europe/Warsaw"
                    },
                    "type": "loading"
                }
            ],
            "place": {
                "address": {
                    "country": "pl",
                    "description": null,
                    "locality": "Wroclaw",
                    "number": null,
                    "postal_code": "54-128",
                    "street": null
                },
                "coordinates": {
                    "latitude": 51.142329074,
                    "longitude": 16.937462521
                }
            },
            "spot_order": 1
        },
        {
            "description": "",
            "name": null,
            "operations": [
                {
                    "loads": [
                        {
                            "load_id": "3766404",
                            "weight": null
                        }
                    ],
                    "operation_order": 1,
                    "operation_time": null,
                    "timespans": {
                        "begin": "2026-02-26T17:30:58+01:00",
                        "begin_local": "2026-02-26T17:30:58+01:00",
                        "end": "2026-02-26T18:30:58+01:00",
                        "end_local": "2026-02-26T18:30:58+01:00",
                        "timezone": "Europe/San_Marino"
                    },
                    "type": "unloading"
                }
            ],
            "place": {
                "address": {
                    "country": "it",
                    "description": null,
                    "locality": "Milan",
                    "number": null,
                    "postal_code": "20097",
                    "street": null
                },
                "coordinates": {
                    "latitude": 45.397205283,
                    "longitude": 9.21659417
                }
            },
            "spot_order": 2
        }
    ],
    "status": "new",
    "surcharges": [],
    "transit_time": null,
    "volume": null,
    "width": null
}

Client errors (code 400)

HTTP 4xx sta­tus codes indi­cate client errors, mean­ing that the request could not be processed due to an issue on the client side. Below is a list of request-spe­cif­ic errors.

Example error 1

No manda­to­ry val­ue in capac­i­ty field

{
    "detail": "Failed Validation",
    "status": 422,
    "title": "Unprocessable Entity",
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html",
    "validation_messages": {
        "capacity": {
            "value": {
                "isEmpty": "Value is required and can't be empty"
            }
        }
    }
}
Example error 2

Incor­rect date in spot oper­a­tion

"validation_messages": {
        "spot_operation": {
            "validation_error": "In one of spot.operation begin or end date is lower or equal today (UTC)"
        }
    }
Example error 3

Vehi­cle type not allowed for vehi­cle size

"validation_messages": {
            "vehicle_size_id": {
                "invalid": "['7_silos'] is not valid for vehicle size: '1_bus'"
            }
        }
    }
Example error 4

Incor­rect freight sta­tus

{
    "detail": "You cant update freight (id: 3823550) with status: 'in_progress'",
    "status": 403,
    "title": "Forbidden",
    "type": "http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}