Create Logistics Recharges (Bulk)

Create multiple logistics recharges (fuel consumption records) in a single request

POST /v1/logistics/recharges/bulk

Create Logistics Recharges (Bulk)

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({records: [{}], options: {}})
};

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

200

{
  "created": 123,
  "updated": 123,
  "errors": [
    {
      "index": 123,
      "message": "<string>"
    }
  ]
}

Create Logistics Recharges (Bulk)

Create multiple fuel consumption records in a single API call. Optimized for batch processing of up to 5,000 records per request.

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

records · array · required

Array of recharge records to create (1 to 5,000). Each record uses the same format as the single POST /recharges endpoint.

Each record contains:

• fuel_id (string, required): UUID of the fuel type
• country (string, required): ISO 3166-1 alpha-2 country code
• date (string, required): Date in YYYY-MM-DD format
• quantity (number): Amount of fuel consumed
• vehicle_license_plate (string): Vehicle license plate
• toc_id (string): UUID of the vehicle type
• project_id (string): UUID of a project to associate with

options · object

Processing options for the bulk operation.

• continue_on_error (boolean, default: true): If true, continues processing remaining records even if some fail. If false, stops at the first error.

Response

Returns a summary of the bulk operation with HTTP 201.

created · integer

Number of successfully created recharges

updated · integer

Number of recharges that matched an existing record and were updated (upsert)

errors · array

Array of error objects for records that failed to process

Show Error object

index · integer

Zero-based index of the failed record in the input array

message · string

Description of the error

Example

cURL

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

Successful Response

{
  "total_received": 3,
  "total_processed": 3,
  "success": 2,
  "failed": 1,
  "results": [
    { "index": 0, "id": "660e8400-e29b-41d4-a716-446655440000" },
    { "index": 2, "id": "770e8400-e29b-41d4-a716-446655440000" }
  ],
  "errors": [
    { "index": 1, "error": "Fuel with id '...' not found or inactive" }
  ]
}

Field	Type	Description
total_received	integer	Number of records in the request
total_processed	integer	Records processed (success + failed)
success	integer	Records created/updated successfully
failed	integer	Records that failed validation
results	array	Successfully processed records with their IDs
errors	array	Error details for failed records

Upsert Behavior

Records with the same combination of country, date, quantity, and vehicle_license_plate within the organization are updated instead of duplicated. This matches the deduplication behavior of CSV file uploads.

Daily Batch Upload from CSV

import pandas as pd
import requests

df = pd.read_csv("daily_recharges.csv")

records = [
    {
        "fuel_id": row["fuel_id"],
        "country": row["country"],
        "date": row["date"],
        "quantity": row["quantity"],
        "vehicle_license_plate": row["plate"]
    }
    for _, row in df.iterrows()
]

response = requests.post(
    "https://api.dcycle.io/v1/logistics/recharges/bulk",
    headers=headers,
    json={"records": records, "options": {"continue_on_error": True}}
)

result = response.json()
print(f"Processed: {result['success']}/{result['total_received']}")

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

422 Validation Error

Cause: Empty records array or exceeding 5,000 records.

{
  "detail": [
    {
      "loc": ["body", "records"],
      "msg": "ensure this value has at most 5000 items"
    }
  ]
}

Partial Failures

When continue_on_error is true (default), individual record failures are reported in the errors array while successfully processed records are included in results. Common per-record errors:

• Invalid fuel_id: Fuel not found or inactive
• Invalid country: Not Valid Country Code, must be ISO 3166-1 alpha-2

Related Endpoints

Create Recharge

Create a single recharge

List Recharges

Retrieve fuel consumption records

Batch Delete Recharges

Delete multiple recharges at once

Create Requests (Bulk)

Bulk create shipment requests