Create Logistics Recharge

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fuel_id: '<string>',
    country: '<string>',
    date: '<string>',
    quantity: 123,
    vehicle_license_plate: '<string>',
    toc_id: '<string>',
    project_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/logistics/recharges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/logistics/recharges"

payload = {
    "fuel_id": "<string>",
    "country": "<string>",
    "date": "<string>",
    "quantity": 123,
    "vehicle_license_plate": "<string>",
    "toc_id": "<string>",
    "project_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/logistics/recharges \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "fuel_id": "<string>",
  "country": "<string>",
  "date": "<string>",
  "quantity": 123,
  "vehicle_license_plate": "<string>",
  "toc_id": "<string>",
  "project_id": "<string>"
}
'

{
  "id": "<string>",
  "fuel_id": "<string>",
  "fuel_name": "<string>",
  "country": "<string>",
  "date": "<string>",
  "quantity": 123,
  "vehicle_license_plate": {},
  "toc_id": {},
  "unit_name": "<string>",
  "status": "<string>",
  "created_at": {},
  "updated_at": {}
}

POST

logistics

recharges

Create Logistics Recharge

const options = {
  method: 'POST',
  headers: {
    'x-api-key': '<x-api-key>',
    'x-organization-id': '<x-organization-id>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fuel_id: '<string>',
    country: '<string>',
    date: '<string>',
    quantity: 123,
    vehicle_license_plate: '<string>',
    toc_id: '<string>',
    project_id: '<string>'
  })
};

fetch('https://api.dcycle.io/v1/logistics/recharges', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.dcycle.io/v1/logistics/recharges"

payload = {
    "fuel_id": "<string>",
    "country": "<string>",
    "date": "<string>",
    "quantity": 123,
    "vehicle_license_plate": "<string>",
    "toc_id": "<string>",
    "project_id": "<string>"
}
headers = {
    "x-api-key": "<x-api-key>",
    "x-organization-id": "<x-organization-id>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

curl --request POST \
  --url https://api.dcycle.io/v1/logistics/recharges \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "fuel_id": "<string>",
  "country": "<string>",
  "date": "<string>",
  "quantity": 123,
  "vehicle_license_plate": "<string>",
  "toc_id": "<string>",
  "project_id": "<string>"
}
'

{
  "id": "<string>",
  "fuel_id": "<string>",
  "fuel_name": "<string>",
  "country": "<string>",
  "date": "<string>",
  "quantity": 123,
  "vehicle_license_plate": {},
  "toc_id": {},
  "unit_name": "<string>",
  "status": "<string>",
  "created_at": {},
  "updated_at": {}
}

← Logistics API Create a new fuel consumption record for a logistics vehicle. A recharge records fuel usage (diesel, electric, etc.) linked to a specific fuel type and optionally a vehicle and project.

Request

Headers

string

required

Your API key for authenticationExample: sk_live_1234567890abcdef

string

required

Your organization UUIDExample: a8315ef3-dd50-43f8-b7ce-d839e68d51fa

Body Parameters

string

required

UUID of the fuel type from the logistic_fuels table. Use GET /logistics/fuels to list all available fuel IDs and their names.Example: 550e8400-e29b-41d4-a716-446655440000

string

required

Country ISO 3166-1 alpha-2 code where the recharge took place.Example: ES

string

required

Date of the recharge in YYYY-MM-DD format.Example: 2025-06-15

number

Amount of fuel consumed, in the fuel’s unit (e.g., liters for diesel, kWh for electricity).Example: 50.0

string

License plate of the vehicle that was refueled.Example: 1234-ABC

string

UUID of the vehicle type (TOC) associated with this recharge. Use the GET /tocs endpoint to get available TOC IDs.No published endpoint returns this id: both GET /v1/logistics/tocs and the legacy GET /api/v1/logistics/tocs return the toc string (<vehicle>_<type>) without the row id. Leave it out and let the calculation resolve the TOC from the shipment data, or ask support for the id you need

string

UUID of a project to associate this recharge with.Retrieve available options from GET /v1/projects/extended

Response

Returns the created (or upserted) recharge with HTTP 201.

string

Recharge UUID

string

UUID of the fuel type

string

Display name of the fuel (e.g. Diesel, Electricity)

string

ISO-2 country code

date

Recharge date (ISO 8601)

number

Fuel quantity in the fuel’s unit

string | null

License plate of the vehicle

string | null

UUID of the associated vehicle type (TOC)

string

Unit of measurement (e.g. liters, kWh, kg)

string

Record status: active or deleted

datetime

Creation timestamp (ISO 8601)

datetime | null

Last update timestamp (ISO 8601)

Example

curl -X POST "https://api.dcycle.io/v1/logistics/recharges" \
  -H "x-api-key: ${DCYCLE_API_KEY}" \
  -H "x-organization-id: ${DCYCLE_ORG_ID}" \
  -H "Content-Type: application/json" \
  -d '{
    "fuel_id": "550e8400-e29b-41d4-a716-446655440000",
    "country": "ES",
    "date": "2025-06-15",
    "quantity": 50.0,
    "vehicle_license_plate": "1234-ABC"
  }'

import requests
import os

api_key = os.getenv("DCYCLE_API_KEY")
org_id = os.getenv("DCYCLE_ORG_ID")

headers = {
    "x-api-key": api_key,
    "x-organization-id": org_id,
    "Content-Type": "application/json"
}

response = requests.post(
    "https://api.dcycle.io/v1/logistics/recharges",
    headers=headers,
    json={
        "fuel_id": "550e8400-e29b-41d4-a716-446655440000",
        "country": "ES",
        "date": "2025-06-15",
        "quantity": 50.0,
        "vehicle_license_plate": "1234-ABC"
    }
)

result = response.json()
print(f"Recharge ID: {result['id']}")
print(f"Fuel: {result['fuel_name']}")

const axios = require('axios');

const apiKey = process.env.DCYCLE_API_KEY;
const orgId = process.env.DCYCLE_ORG_ID;

const headers = {
  'x-api-key': apiKey,
  'x-organization-id': orgId,
  'Content-Type': 'application/json'
};

axios.post(
  'https://api.dcycle.io/v1/logistics/recharges',
  {
    fuel_id: '550e8400-e29b-41d4-a716-446655440000',
    country: 'ES',
    date: '2025-06-15',
    quantity: 50.0,
    vehicle_license_plate: '1234-ABC'
  },
  { headers }
)
.then(response => {
  console.log(`Recharge ID: ${response.data.id}`);
  console.log(`Fuel: ${response.data.fuel_name}`);
})
.catch(error => console.error(error));

Successful Response

{
  "id": "660e8400-e29b-41d4-a716-446655440000",
  "fuel_id": "550e8400-e29b-41d4-a716-446655440000",
  "fuel_name": "Diesel",
  "country": "ES",
  "date": "2025-06-15T00:00:00",
  "quantity": 50.0,
  "vehicle_license_plate": "1234-ABC",
  "toc_id": null,
  "unit_name": "liters",
  "status": "active",
  "created_at": "2025-06-15T10:30:00",
  "updated_at": "2025-06-15T10:30:00"
}

Upsert Behavior

If a recharge with the same combination of country, date, quantity, and vehicle_license_plate already exists within the organization, the existing record is updated instead of creating a duplicate.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

{"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: The fuel_id does not exist or is inactive.

{
  "code": "NOT_FOUND",
  "detail": "Fuel with id '550e8400-e29b-41d4-a716-446655440000' not found or inactive"
}

Solution: Use GET /logistics/fuels to get the full list of valid fuel IDs.

422 Validation Error

Cause: Missing required fields or invalid country code.

{
  "detail": [
    {
      "loc": ["body", "country"],
      "msg": "Not Valid Country Code, must be ISO 3166-1 alpha-2"
    }
  ]
}

Create Recharges (Bulk)

Create up to 5,000 recharges in one request

List Recharges

Retrieve fuel consumption records

Delete Recharge

Delete a single recharge

List Vehicle Types (TOCs)

List available vehicle types

List Fuel Types

List all available fuel types and their IDs

​Request

​Headers

​Body Parameters

​Response

​Example

​Successful Response

​Upsert Behavior

​Common Errors

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​Related Endpoints

Create Recharges (Bulk)

List Recharges

Delete Recharge

List Vehicle Types (TOCs)

List Fuel Types

Request

Headers

Body Parameters

Response

Example

Successful Response

Upsert Behavior

Common Errors

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

Related Endpoints