Update Transport Route

Update a transport route and replace all its sections

PUT /v1/transports/{transport_route_id}

Update Transport Route

JavaScript

const options = {
  method: 'PUT',
  headers: {'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>',
    sections: [
      {
        'sections[].transport_type': '<string>',
        'sections[].travel_method': '<string>',
        'sections[].electric': true,
        'sections[].refrigerated': 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));

200

{
  "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 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

Authentication

Supports both authentication methods:

x-api-key · string

Your API key (use this or Authorization)

Example: sk_live_1234567890abcdef

Authorization · string

Bearer JWT token (use this or x-api-key)

Example: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Headers

x-organization-id · string · required

Your organization UUID

Example: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

transport_route_id · string · required

The unique identifier (UUID) of the transport route to update

Example: 010ed3b6-b513-40f3-b9fe-0f0a338d9274

Body

name · string

Optional route name

transport_date · string

Date of transport in YYYY-MM-DD format

Example: 2024-06-15

quantity_transported · number

Amount transported. Must be greater than 0, max 10 digits with 3 decimal places

Example: 2500.000

supplier · string

Optional supplier name

Example: LogiTrans S.A.

transport_frequency · string

Recurrence of this route. One of: once, weekly, monthly

unit_id · string

UUID of the measurement unit for quantity_transported

Example: 61743a63-ff70-459c-9567-5eee8f7dfd5c

sections · array · required

List of transport sections (legs). Must contain at least 1 item. Replaces all existing sections.

Show section fields

sections[].transport_type · string · required

Mode of transport: road, air, maritime, rail, do_not_know

sections[].travel_method · string

Sub-type for road segments: car, truck, motorbike, bicycle, electric_kick_scooter

sections[].electric · boolean · required

Whether the vehicle is electric

sections[].refrigerated · boolean · required

Whether the cargo is refrigerated

sections[].detail · 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:3500

sections[].origin · string

Origin location address used for automatic distance calculation

Example: Barcelona, Spain

sections[].destination · string

Destination location address used for automatic distance calculation

Example: Latakia, Syria

sections[].kms_manual · number

Distance override in kilometers. Skips automatic distance calculation when set. Must be greater than 0, max 7 digits with 2 decimal places

Example: 4626.00

Response

Returns the updated TransportRouteSch object with status 201 Created.

id · string

Unique identifier (UUID)

name · string | null

Optional route name

transport_date · date

Date of transport (YYYY-MM-DD). null if not set

quantity_transported · number

Amount transported (max 10 digits, 3 decimal places)

supplier · string | null

Optional supplier name

transport_direction · string

downstream or upstream

transport_frequency · string

Recurrence: once, weekly, monthly

unit · object

Measurement unit for the quantity transported

Show unit fields

unit.id · string

UUID of the unit

unit.name · string

Unit name, e.g. kilogram_(kg), metric_tonne_(t)

unit.type · string

Unit type, e.g. solid, liquid

status · string

Route status: pending immediately after update (recalculation in progress), active once complete, error if calculation failed

co2e · number | null

Total CO2-equivalent emissions in kg. null while recalculation is in progress

emissions · array

Route-level emissions summary: [{"value": 245.67, "gas": "co2e", "unit_name": "kgCO2e"}]

sections · array

Newly created sections. Emissions fields will be null until asynchronous calculation completes. See Get Transport Route for the full section schema

file_id · string | null

ID of the file if this route was created via bulk upload

created_at · datetime

ISO 8601 creation timestamp

updated_at · datetime

ISO 8601 last-update timestamp

Example

cURL

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,
        "origin": "Madrid, Spain",
        "destination": "Barcelona Port, Spain"
      },
      {
        "transport_type": "maritime",
        "electric": false,
        "refrigerated": false,
        "origin": "Barcelona Port, Spain",
        "destination": "Latakia Port, Syria"
      }
    ]
  }'

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