Skip to main content
POST
Create Logistics Recharge
← 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
UUID of the fuel type from the logistic_fuels table. Use GET /logistics/fuels to list all available fuel IDs and their names. Send this or fuel, not both.Example: 550e8400-e29b-41d4-a716-446655440000
string
Fuel type, the name in GET /logistics/fuels (e.g. diesel). The variant for the recharge’s country is used, as in a file import: the country’s region, else global, else EU, else any region. GET /logistics/fuels?country= lists the variant each type gets. Send this or fuel_id, not both.Example: diesel
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, a year from 1970 to next year.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
string
UUID of an uploaded file of your organization’s files to attach to the recharge as its supporting document, e.g. the fuel ticket or the fuel card statement. Not the file the recharge was read from. A file you cannot attach (unknown, pending, in the trash or of another organization) answers 404 NOT_FOUND naming File, and nothing is written. A recharge that repeats an existing one (see Upsert Behavior) attaches it to that one.

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)
boolean
true when a recharge with the same country, date, quantity and vehicle_license_plate already existed and was updated instead of adding one (see Upsert Behavior); false when the recharge is new.
object | null
The document attached to the recharge (attachment_file_id), or null. Not the file the recharge was read from (file_id). A file deleted or moved to the trash is no longer attached.

Example

Successful Response

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, and the response has updated_existing: true. With a project_id, a recharge already linked to that project stays linked once.

Common Errors

401 Unauthorized

Cause: Missing or invalid API key

403 Forbidden

Cause: The authenticated user is not a member of the organization

404 Not Found

Cause: The fuel_id does not exist or is inactive, or no fuel matches fuel.
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.

422 Country without fuel factors

Cause: fuel was sent with a country that has no region with fuel factors (such as AQ or BV), so no variant applies.
Solution: Send the fuel_id of the fuel to use.

422 Activity date out of range

Cause: date has a year before 1970 or after next year (e.g. 0100-01-01, a typo of 2001-01-01)
Solution: Send the real date of the recharge.

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