Update Transport Route
const options = {
method: 'PUT',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
transport_date: '<string>',
quantity_transported: 123,
supplier: '<string>',
transport_frequency: '<string>',
unit_id: '<string>',
spend_amount: 123,
currency_unit_id: '<string>',
multidb: true,
sections: [
{
'sections[].transport_type': '<string>',
'sections[].travel_method': '<string>',
'sections[].electric': true,
'sections[].refrigerated': true,
'sections[].distance_manual': true,
'sections[].detail': '<string>',
'sections[].origin': '<string>',
'sections[].destination': '<string>',
'sections[].kms_manual': 123
}
]
})
};
fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/transports/{transport_route_id}"
payload = {
"name": "<string>",
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": "<string>",
"transport_frequency": "<string>",
"unit_id": "<string>",
"spend_amount": 123,
"currency_unit_id": "<string>",
"multidb": True,
"sections": [
{
"sections[].transport_type": "<string>",
"sections[].travel_method": "<string>",
"sections[].electric": True,
"sections[].refrigerated": True,
"sections[].distance_manual": True,
"sections[].detail": "<string>",
"sections[].origin": "<string>",
"sections[].destination": "<string>",
"sections[].kms_manual": 123
}
]
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)curl --request PUT \
--url https://api.dcycle.io/v1/transports/{transport_route_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"name": "<string>",
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": "<string>",
"transport_frequency": "<string>",
"unit_id": "<string>",
"spend_amount": 123,
"currency_unit_id": "<string>",
"multidb": true,
"sections": [
{
"sections[].transport_type": "<string>",
"sections[].travel_method": "<string>",
"sections[].electric": true,
"sections[].refrigerated": true,
"sections[].distance_manual": true,
"sections[].detail": "<string>",
"sections[].origin": "<string>",
"sections[].destination": "<string>",
"sections[].kms_manual": 123
}
]
}
'{
"id": "<string>",
"name": {},
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": {},
"transport_direction": "<string>",
"transport_frequency": "<string>",
"unit": {
"unit.id": "<string>",
"unit.name": "<string>",
"unit.type": "<string>"
},
"status": "<string>",
"co2e": {},
"emissions": [
{}
],
"sections": [
{}
],
"file_id": {},
"created_at": {},
"updated_at": {}
}Update Transport Route
Update a transport route and replace all its sections
PUT
/
v1
/
transports
/
{transport_route_id}
Update Transport Route
const options = {
method: 'PUT',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: '<string>',
transport_date: '<string>',
quantity_transported: 123,
supplier: '<string>',
transport_frequency: '<string>',
unit_id: '<string>',
spend_amount: 123,
currency_unit_id: '<string>',
multidb: true,
sections: [
{
'sections[].transport_type': '<string>',
'sections[].travel_method': '<string>',
'sections[].electric': true,
'sections[].refrigerated': true,
'sections[].distance_manual': true,
'sections[].detail': '<string>',
'sections[].origin': '<string>',
'sections[].destination': '<string>',
'sections[].kms_manual': 123
}
]
})
};
fetch('https://api.dcycle.io/v1/transports/{transport_route_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/transports/{transport_route_id}"
payload = {
"name": "<string>",
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": "<string>",
"transport_frequency": "<string>",
"unit_id": "<string>",
"spend_amount": 123,
"currency_unit_id": "<string>",
"multidb": True,
"sections": [
{
"sections[].transport_type": "<string>",
"sections[].travel_method": "<string>",
"sections[].electric": True,
"sections[].refrigerated": True,
"sections[].distance_manual": True,
"sections[].detail": "<string>",
"sections[].origin": "<string>",
"sections[].destination": "<string>",
"sections[].kms_manual": 123
}
]
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.put(url, json=payload, headers=headers)
print(response.text)curl --request PUT \
--url https://api.dcycle.io/v1/transports/{transport_route_id} \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"name": "<string>",
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": "<string>",
"transport_frequency": "<string>",
"unit_id": "<string>",
"spend_amount": 123,
"currency_unit_id": "<string>",
"multidb": true,
"sections": [
{
"sections[].transport_type": "<string>",
"sections[].travel_method": "<string>",
"sections[].electric": true,
"sections[].refrigerated": true,
"sections[].distance_manual": true,
"sections[].detail": "<string>",
"sections[].origin": "<string>",
"sections[].destination": "<string>",
"sections[].kms_manual": 123
}
]
}
'{
"id": "<string>",
"name": {},
"transport_date": "<string>",
"quantity_transported": 123,
"supplier": {},
"transport_direction": "<string>",
"transport_frequency": "<string>",
"unit": {
"unit.id": "<string>",
"unit.name": "<string>",
"unit.type": "<string>"
},
"status": "<string>",
"co2e": {},
"emissions": [
{}
],
"sections": [
{}
],
"file_id": {},
"created_at": {},
"updated_at": {}
}Update an existing transport route’s metadata and sections. When
sections is provided it completely replaces all existing sections — partial section patches are not supported. After a successful update, emissions are recalculated asynchronously and the route status is reset to pending.
Sending
sections deletes all existing sections and creates new ones. Any previously calculated distances and emissions for those sections are discarded and recalculated from scratch.Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faPath Parameters
string
required
The unique identifier (UUID) of the transport route to updateExample:
010ed3b6-b513-40f3-b9fe-0f0a338d9274Body
string
Optional route name
string
Date of transport in
YYYY-MM-DD formatExample: 2024-06-15number
Amount transported. Must be greater than 0, up to 999,999,999.99999: 9 integer digits, 5 decimal placesExample:
2500.000string
Optional supplier nameExample:
LogiTrans S.A.string
Recurrence of this route. One of:
once, weekly, monthlystring
UUID of the measurement unit for
quantity_transportedExample: 61743a63-ff70-459c-9567-5eee8f7dfd5cnumber
Optional: what the whole shipment cost, over 0, in
currency_unit_id. Sent, it replaces the stored one, and null
(with currency_unit_id: null) removes it. It is calculated as in
What a shipment cost: the distance keeps the priority,
and the spend prices the shipment when its distance cannot, including when a section’s distance cannot be had
(the request is not refused for it). With it, quantity_transported, unit_id and the
sections’ distances become optional. Send it with currency_unit_id and multidb: true (422 otherwise). A
PUT that leaves it out keeps the stored spend, which prices the shipment only with multidb: true: send
multidb: true on every PUT of a shipment with a spend, and quantity_transported and unit_id when the PUT
leaves the spend out.string
The currency of
spend_amount, a unit of type fiat_currency from List Units
(422 INVALID_CURRENCY_UNIT otherwise). Send it with spend_amount, and only with it.boolean
true calculates the shipment with the emission factor databases
Create Transports (v2) uses; left out or false, with the previous
calculation. A spend_amount needs true.array
required
List of transport sections (legs). Must contain at least 1 item. Replaces all existing sections.
Show section fields
Show section fields
string
required
Mode of transport:
road, air, maritime, rail, do_not_knowstring
Sub-type for road segments:
car, truck, motorbike, bicycle, electric_kick_scooterboolean
default:"false"
Whether the vehicle is electric. Sections are replaced, so an omitted value is stored as
false.boolean
default:"false"
Whether the cargo is refrigerated. Sections are replaced, so an omitted value is stored as
false.boolean
required
Whether the distance is manually provided via
kms_manual. Set to true when providing kms_manual, or false when using origin/destination geocoding.string
Additional detail for emission factor selection. Distance bands:
distance:ge:4000, distance:ge:1500, distance:ge:800, distance:lt:800. Weight classes: weight:ge:32000, weight:ge:16000, weight:ge:7500, weight:ge:3500string
Origin location address used for automatic distance calculationExample:
Barcelona, Spainstring
Destination location address used for automatic distance calculationExample:
Latakia, Syrianumber
Distance override in kilometers. Skips automatic distance calculation when set. Must be greater than 0, up to 8 integer digits, 6 decimal placesExample:
4626.00Response
Returns the updatedTransportRouteSch object with status 201 Created.
string
Unique identifier (UUID)
string | null
Optional route name
date
Date of transport (YYYY-MM-DD).
null if not setnumber
Amount transported (up to 999,999,999.99999: 9 integer digits, 5 decimal places)
string | null
Optional supplier name
string
downstream or upstreamstring
Recurrence:
once, weekly, monthlyobject
string
Route status:
pending immediately after update (recalculation in progress), active once complete, error if calculation failednumber | null
Total CO2-equivalent emissions in kg.
null while recalculation is in progressarray
Route-level emissions summary:
[{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}]array
Newly created sections. Emissions fields will be
null until asynchronous calculation completes. See Get Transport Route for the full section schemastring | null
ID of the file if this route was created via bulk upload
datetime
ISO 8601 creation timestamp
datetime | null
ISO 8601 last-update timestamp
Example
curl -X PUT "https://api.dcycle.io/v1/transports/010ed3b6-b513-40f3-b9fe-0f0a338d9274" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"name": "Madrid to Syria Shipment (revised)",
"transport_date": "2024-07-01",
"quantity_transported": 2500.000,
"supplier": "LogiTrans S.A.",
"transport_frequency": "once",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"sections": [
{
"transport_type": "road",
"travel_method": "truck",
"electric": false,
"refrigerated": false,
"distance_manual": false,
"origin": "Madrid, Spain",
"destination": "Barcelona Port, Spain"
},
{
"transport_type": "maritime",
"electric": false,
"refrigerated": false,
"distance_manual": false,
"origin": "Barcelona Port, Spain",
"destination": "Latakia Port, Syria"
}
]
}'
import requests
import os
route_id = "010ed3b6-b513-40f3-b9fe-0f0a338d9274"
response = requests.put(
f"https://api.dcycle.io/v1/transports/{route_id}",
headers={
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID"),
},
json={
"name": "Madrid to Syria Shipment (revised)",
"transport_date": "2024-07-01",
"quantity_transported": 2500.000,
"supplier": "LogiTrans S.A.",
"transport_frequency": "once",
"unit_id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"sections": [
{
"transport_type": "road",
"travel_method": "truck",
"electric": False,
"refrigerated": False,
"distance_manual": False,
"origin": "Madrid, Spain",
"destination": "Barcelona Port, Spain",
},
{
"transport_type": "maritime",
"electric": False,
"refrigerated": False,
"distance_manual": False,
"origin": "Barcelona Port, Spain",
"destination": "Latakia Port, Syria",
},
],
},
)
route = response.json()
print(f"Updated route: {route['id']}, status: {route['status']}")
print(f"Sections replaced: {len(route['sections'])}")
const axios = require('axios');
const routeId = '010ed3b6-b513-40f3-b9fe-0f0a338d9274';
axios.put(
`https://api.dcycle.io/v1/transports/${routeId}`,
{
name: 'Madrid to Syria Shipment (revised)',
transport_date: '2024-07-01',
quantity_transported: 2500.0,
supplier: 'LogiTrans S.A.',
transport_frequency: 'once',
unit_id: '61743a63-ff70-459c-9567-5eee8f7dfd5c',
sections: [
{
transport_type: 'road',
travel_method: 'truck',
electric: false,
refrigerated: false,
distance_manual: false,
origin: 'Madrid, Spain',
destination: 'Barcelona Port, Spain',
},
{
transport_type: 'maritime',
electric: false,
refrigerated: false,
distance_manual: false,
origin: 'Barcelona Port, Spain',
destination: 'Latakia Port, Syria',
},
],
},
{
headers: {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
},
}
)
.then(({ data: route }) => {
console.log(`Updated route: ${route.id}, status: ${route.status}`);
console.log(`Sections replaced: ${route.sections.length}`);
});
Successful Response
{
"id": "010ed3b6-b513-40f3-b9fe-0f0a338d9274",
"name": "Madrid to Syria Shipment (revised)",
"transport_date": "2024-07-01",
"quantity_transported": 2500.0,
"supplier": "LogiTrans S.A.",
"transport_direction": "downstream",
"transport_frequency": "once",
"unit": {
"id": "61743a63-ff70-459c-9567-5eee8f7dfd5c",
"name": "kilogram_(kg)",
"type": "solid"
},
"status": "pending",
"co2e": null,
"emissions": null,
"file_id": null,
"sections": [
{
"id": "7a1b2c3d-0000-0000-0000-000000000001",
"part": 1,
"transport_type": "road",
"travel_method": "truck",
"electric": false,
"refrigerated": false,
"detail": null,
"origin": "Madrid, Spain",
"destination": "Barcelona Port, Spain",
"kms": null,
"kms_manual": null,
"distance_manual": false,
"kms_source": null,
"status": "pending",
"step": null,
"error_messages": null,
"emissions": null,
"created_at": "2024-07-01T10:00:00Z",
"updated_at": "2024-07-01T10:00:00Z"
},
{
"id": "7a1b2c3d-0000-0000-0000-000000000002",
"part": 2,
"transport_type": "maritime",
"travel_method": null,
"electric": false,
"refrigerated": false,
"detail": null,
"origin": "Barcelona Port, Spain",
"destination": "Latakia Port, Syria",
"kms": null,
"kms_manual": null,
"distance_manual": false,
"kms_source": null,
"status": "pending",
"step": null,
"error_messages": null,
"emissions": null,
"created_at": "2024-07-01T10:00:00Z",
"updated_at": "2024-07-01T10:00:00Z"
}
],
"created_at": "2024-06-10T09:00:00Z",
"updated_at": "2024-07-01T10:00:00Z"
}
The response status will be
pending immediately after the update. Poll Get Transport Route or use Get Route Counts to track when recalculation completes.Common Errors
401 Unauthorized
Cause: Missing or invalid API key / JWT token{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
403 Forbidden
Cause: The authenticated user is not a member of the organization{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
404 Not Found
Cause: Route ID does not exist or belongs to a different organization{"detail": "TransportRoute not found", "code": "TRANSPORT_ROUTE_NOT_FOUND"}
422 Unprocessable Entity
Cause: Validation error — e.g.sections is empty, quantity_transported is zero or negative, or an enum value is invalid
{
"detail": [
{
"loc": ["body", "sections"],
"msg": "ensure this value has at least 1 items",
"type": "value_error.list.min_items"
}
]
}
Related Endpoints
Get Transport Route
Retrieve a route by ID to check recalculation progress
Create Transport Route
Create a new transport route with sections
Delete Transport Route
Remove a transport route permanently
Get Route Counts
Monitor pending, active, and error counts
List Transport Routes
Retrieve all transport routes with filtering and pagination
Transport Overview
Full data model and distance calculation reference
Was this page helpful?