Create Logistics Recharge

Create a single logistics recharge (fuel consumption record) for your organization

POST /v1/logistics/recharges

Create Logistics Recharge

JavaScript

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

200

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

Create Logistics Recharge

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

x-api-key · string · required

Your API key for authentication

Example: sk_live_1234567890abcdef

x-organization-id · string · required

Your organization UUID

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

Body Parameters

fuel_id · 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

country · string · required

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

Example: ES

date · string · required

Date of the recharge in YYYY-MM-DD format.

Example: 2025-06-15

quantity · number

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

Example: 50.0

vehicle_license_plate · string

License plate of the vehicle that was refueled.

Example: 1234-ABC

toc_id · string

UUID of the vehicle type (TOC) associated with this recharge. Use the GET /tocs endpoint to get available TOC IDs.

project_id · string

UUID of a project to associate this recharge with.

Response

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

id · string

Recharge UUID

fuel_id · string

UUID of the fuel type

fuel_name · string

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

country · string

ISO-2 country code

date · date

Recharge date (ISO 8601)

quantity · number

Fuel quantity in the fuel’s unit

vehicle_license_plate · string | null

License plate of the vehicle

toc_id · string | null

UUID of the associated vehicle type (TOC)

unit_name · string

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

status · string

Record status: active or deleted

created_at · datetime

Creation timestamp (ISO 8601)

updated_at · datetime | null

Last update timestamp (ISO 8601)

Example

cURL

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

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

Related Endpoints

Create Recharges (Bulk)

Create up to 5,000 recharges in one request

List Recharges

Retrieve fuel consumption records

Delete Recharge

Delete a single recharge

Get Vehicle Types (TOCs)

List available vehicle types

List Fuel Types

List all available fuel types and their IDs