Customer Transactions API

Overview

The Neutral Fuels Customer Transactions API gives you programmatic, read-only access to your own fuel-card transaction data. It is designed for backend integrations - ETL pipelines, dashboards, fleet/telematics platforms, and accounting reconciliation.

Endpoints at a glance

Authentication

Every request must include your API key in the X-API-Key header:

X-API-Key: nfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Your key is issued by Neutral Fuels and is tied to one account. There is no parameter to request another account's data - the account is derived from the key.
• Keys begin with the prefix nfk_. Treat your key like a password.
• A missing, unknown, disabled, or expired key returns 401 with body {"detail":"Invalid API key"}. Disabling or rotating a key takes effect immediately.

Quickstart

Confirm your key and see your quota:

curl -H "X-API-Key: nfk_YOUR_KEY" \
  "https://myportal-api.neutralfuels.net/api/v1/external/health"

{
  "mcs_customer_id": 42,
  "customer_name": "Your Company",
  "usage": { "day": { "used": 1, "limit": 30 }, "minute": { "used": 1, "limit": 5 } }
}

Then pull a month of transactions:

curl -H "X-API-Key: nfk_YOUR_KEY" \
  "https://myportal-api.neutralfuels.net/api/v1/external/transactions?start_date=2026-05-01&end_date=2026-05-31&limit=100"

Conventions

• Dates (start_date, end_date) use the format YYYY-MM-DD - e.g. 2026-05-31.
• Timestamps in responses are ISO 8601 with a timezone offset, in your account's local timezone - e.g. 2026-06-07T20:10:00+04:00. The timezone is also returned as meta.timezone (e.g. Asia/Dubai).
• The date range is inclusive of the whole end day - end_date=2026-05-31 includes transactions up to 23:59:59 local time on 31 May.
• All endpoints are GET; parameters are passed in the query string. Responses are JSON; success is HTTP 200.

List transactions

Returns your fuelling transactions within a date range, most recent first.

Query parameters

The maximum span between start_date and end_date is 366 days; larger ranges return 400. Results are ordered most-recent-first with a stable secondary order, so paging never skips or duplicates rows.

Example request

curl -H "X-API-Key: nfk_YOUR_KEY" \
  "https://myportal-api.neutralfuels.net/api/v1/external/transactions?start_date=2026-05-01&end_date=2026-05-31&limit=500&offset=0"

import requests

r = requests.get(
    "https://myportal-api.neutralfuels.net/api/v1/external/transactions",
    headers={"X-API-Key": "nfk_YOUR_KEY"},
    params={"start_date": "2026-05-01", "end_date": "2026-05-31", "limit": 500},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["meta"]["total"], "transactions")

const url = new URL("https://myportal-api.neutralfuels.net/api/v1/external/transactions");
url.search = new URLSearchParams({ start_date: "2026-05-01", end_date: "2026-05-31", limit: "500" });

const res = await fetch(url, { headers: { "X-API-Key": "nfk_YOUR_KEY" } });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data.meta.total, "transactions");

Example response 200

{
  "data": [
    {
      "transaction_id": 208766590,
      "transaction_datetime": "2026-06-07T20:10:00+04:00",
      "vehicle_no": "93705",
      "vehicle_registration": null,
      "quantity": 120.88,
      "odometer": 1229986.0,
      "odometer_unit_of_measure": null,
      "product_name": "B20",
      "site_name": "Main Depot",
      "pump_no": 1
    }
  ],
  "meta": {
    "count": 1,
    "total": 1843,
    "limit": 1,
    "offset": 0,
    "timezone": "Asia/Dubai",
    "start_date": "2026-05-01",
    "end_date": "2026-05-31"
  }
}

Transaction fields

Meta fields

Health check

A lightweight call to confirm your key is valid and read your current usage. Useful for connectivity checks and monitoring remaining quota.

Example response 200

{
  "mcs_customer_id": 42,
  "customer_name": "Your Company",
  "usage": {
    "day":    { "used": 3, "limit": 30 },
    "minute": { "used": 1, "limit": 5 }
  }
}

Pagination

Responses are paged with limit and offset. Use meta.total to know how many records match, and page until you have them all:

1. Request with offset=0 and your chosen limit (e.g. 500).
2. Read meta.total.
3. Increase offset by limit each call until offset ≥ meta.total (or a page returns fewer than limit records).

Each page is a separate request and counts toward your rate limit, so prefer a larger limit (up to 1000) to reduce the number of calls.

Keeping your data in sync

To pick up new transactions over time, re-fetch a recent date window (for example the last 7 days) on a schedule, and reconcile by transaction_id (insert new ids, update existing ones).

Rate limits

Each API key has two limits:

• A daily limit (default 30 requests/day, resets at 00:00 UTC).
• A per-minute burst limit (default 5 requests/minute).

Every response includes these headers:

When a limit is exceeded the API returns 429 with a Retry-After header (seconds to wait) and body {"detail":"Rate limit exceeded"}. Honour Retry-After and design jobs to stay within your daily quota - fetch each date range once with a large limit rather than polling frequently.

Errors

Error responses are JSON with a detail field:

{ "detail": "date window must be <= 366 days" }

Code examples

A complete, production-ready fetch that handles paging and rate limits.

# pip install requests
import time, requests

BASE = "https://myportal-api.neutralfuels.net"
API_KEY = "nfk_YOUR_KEY"   # load from a secret / env var in production

def fetch_transactions(start_date, end_date, page_size=1000):
    """Yield every transaction in the range, handling paging + 429s."""
    s = requests.Session()
    s.headers["X-API-Key"] = API_KEY
    offset = 0
    while True:
        r = s.get(f"{BASE}/api/v1/external/transactions", timeout=30, params={
            "start_date": start_date, "end_date": end_date,
            "limit": page_size, "offset": offset,
        })
        if r.status_code == 429:
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        r.raise_for_status()
        body = r.json()
        for row in body["data"]:
            yield row
        offset += body["meta"]["limit"]
        if offset >= body["meta"]["total"]:
            break

rows = list(fetch_transactions("2026-05-01", "2026-05-31"))
print(f"Fetched {len(rows)} transactions")

// Node 18+ has built-in fetch (else: npm install node-fetch)
const BASE = "https://myportal-api.neutralfuels.net";
const API_KEY = process.env.NF_API_KEY;   // keep the key out of source control

async function fetchTransactions(startDate, endDate, pageSize = 1000) {
  const all = [];
  let offset = 0;
  while (true) {
    const url = new URL(`${BASE}/api/v1/external/transactions`);
    url.search = new URLSearchParams({
      start_date: startDate, end_date: endDate,
      limit: String(pageSize), offset: String(offset),
    });
    const res = await fetch(url, { headers: { "X-API-Key": API_KEY } });
    if (res.status === 429) {
      await new Promise(r => setTimeout(r, (+res.headers.get("Retry-After") || 60) * 1000));
      continue;
    }
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    const body = await res.json();
    all.push(...body.data);
    offset += body.meta.limit;
    if (offset >= body.meta.total) break;
  }
  return all;
}

const rows = await fetchTransactions("2026-05-01", "2026-05-31");
console.log(`Fetched ${rows.length} transactions`);

Best practices & security

• Keep your key secret. Store it in a secrets manager or environment variable - never in client-side code, mobile apps, browsers, public repositories, or shared documents.
• Use it server-side only. This API is for backend integrations.
• Always use HTTPS. Never send the key over plain HTTP.
• Handle 429 gracefully by honouring Retry-After, and schedule jobs to stay within your daily quota.
• Reconcile by transaction_id so re-fetching a window is idempotent.
• If a key is exposed or no longer needed, contact Neutral Fuels to revoke and reissue it - revocation is immediate.

Support

For API keys, quota changes, or integration help, contact your Neutral Fuels account manager or email us:

oshada.palitharathna@neutralfuels.com