Update Transport Route

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));

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

PUT

transports

{transport_route_id}

Update Transport Route

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));

{
  "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 UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Path Parameters

transport_route_id

string

required

The unique identifier (UUID) of the transport route to updateExample: 010ed3b6-b513-40f3-b9fe-0f0a338d9274

Body

name

string

Optional route name

transport_date

string

Date of transport in YYYY-MM-DD formatExample: 2024-06-15

quantity_transported

number

Amount transported. Must be greater than 0, max 10 digits with 3 decimal placesExample: 2500.000

supplier

string

Optional supplier nameExample: 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_transportedExample: 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 calculationExample: Barcelona, Spain

sections[].destination

string

Destination location address used for automatic distance calculationExample: 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 placesExample: 4626.00

Response

Returns the updated TransportRouteSch object with status 201 Created.

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 -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"
    }
  ]
}

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

Create Transport Route Delete Transport Route

​Update Transport Route

​Request

​Authentication

​Headers

​Path Parameters

​Body

​Response

​Example

​Successful Response

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Unprocessable Entity

​Related Endpoints

Get Transport Route

Create Transport Route

Delete Transport Route

Get Route Counts

List Transport Routes

Transport Overview

Update Transport Route

Request

Authentication

Headers

Path Parameters

Body

Response

Example

Successful Response

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Unprocessable Entity

Related Endpoints