Logistics API & SDK

{
  "success": true,
  "data": { "...": "payload" }
}

{
  "success": false,
  "error": "Folder not found",
  "code": "not_found",
  "status": 404
}

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxx

npm install @logistics/sdk

import { Logistics } from '@logistics/sdk';

const client = new Logistics({
  baseUrl: 'https://api.example.com',
  apiKey: process.env.LOGISTICS_API_KEY,
});

// Everything hangs off the client, grouped by resource.
const shipment = await client.shipments.get('SHP-12345');
const eta      = await client.shipments.eta('SHP-12345');
const vehicles = await client.vehicles.list({ bbox: [3.1, 6.4, 3.5, 6.7] });

const shipment = await client.shipments.create({
  reference: 'SHP-12345',
  originId: 'loc_lagos',
  destinationId: 'loc_abuja',
  carrierId: 'dhl',
  serviceLevel: 'express',
});

// Status history
const timeline = await client.shipments.timeline(shipment.id);

// Move it along
await client.shipments.update(shipment.id, { status: 'in_transit' });

await client.shipments.submitPod(shipment.id, {
  deliveredAt: new Date().toISOString(),
  point: { lat: 9.0765, lng: 7.3986 },
  receivedBy: 'A. Bello',
  photoUrls: ['https://cdn.example.com/pod/123.jpg'],
  note: 'Left with security at gate 2',
});

const status = await client.tracking.get('SHP-12345');
// { reference, status, origin, destination, estimatedAt, confidence }

{
  "eta": "2026-09-19T14:00:00Z",
  "window": { "earliest": "2026-09-19T12:00:00Z", "latest": "2026-09-19T18:00:00Z" },
  "confidence": 0.82,
  "legs": [
    { "sequence": 1, "mode": "road", "eta": "...", "confidence": 0.79, "durationMinutes": 412 }
  ],
  "recalculated": true,
  "computedAt": "2026-09-18T08:00:00Z"
}

await fetch('/v1/positions', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + key, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    vehicleId: 'veh_1',
    point: { lat: 6.5244, lng: 3.3792 },
    speedKph: 48,
    source: 'gps_hardware',
  }),
});

// Snapshot inside a bounding box (minLng,minLat,maxLng,maxLat)
const inView = await client.vehicles.list({ bbox: [3.1, 6.4, 3.5, 6.7] });

// Live stream — polls or uses a socket behind one interface
const stop = client.vehicles.subscribe(
  (ping) => updateMarker(ping.vehicleId, ping.point),
  { vehicleIds: ['veh_1'], intervalMs: 5000, onError: console.error },
);

// later
stop();

await client.geofences.create({
  name: 'Lagos Depot',
  polygon: [[3.35, 6.45], [3.40, 6.45], [3.40, 6.50], [3.35, 6.50]], // [lng, lat]
  triggers: ['enter', 'exit'],
});

// Planned versus actually-travelled polyline for a shipment
const route = await client.vehicles.route('shipment_id');
// { planned: [...], actual: [...], maxDeviationM }

await client.inventory.recordMovement({
  skuId: 'sku_9',
  locationId: 'wh_lagos',
  delta: -3,            // signed: negative is outbound
  uom: 'each',
  reason: 'picked',
  refType: 'order',
  refId: 'ORD-778',
});

// Current levels, including the derived qtyAvailable
const levels = await client.inventory.list({ locationId: 'wh_lagos' });

const result = await client.inventory.cycleCount({
  locationId: 'wh_lagos',
  counts: [{ skuId: 'sku_9', countedQty: 44 }],
  autoAdjustWithinPct: 2,     // beyond this, flag instead of adjust
});
// { adjusted: [...], flagged: [{ skuId, expected, counted, variance, variancePct }] }

const recon = await client.inventory.reconciliation({ locationId: 'wh_lagos' });
// [{ skuId, locationId, systemQty, ledgerQty, variance, lastCountedAt }]

const signals = await client.inventory.reorderSignals();
// [{ skuId, qtyAvailable, reorderPoint, suggestedOrderQty, daysOfCover }]

const conn = await client.sync.createConnector({
  name: 'Shopify Store',
  type: 'shopify',
  direction: 'inbound',
});

// The single most useful number: how far behind is it?
const health = await client.sync.health(conn.id);
// { status, lastSyncAt, lagSeconds, backlog, errorRate, stale }

const preview = await client.sync.dryRun({
  mapping: { 'line_items.0.sku': 'internalCode', 'line_items.0.quantity': 'qty' },
  sample: [shopifyOrder],
});
// { mapped: [...], unmapped: ['...'], errors: [...] }

await client.sync.backfill(conn.id, { from: '2026-09-01', to: '2026-09-18', dryRun: true });

const dead = await client.sync.deadLetters(conn.id);
await client.sync.replay(dead[0].id);

const match = await client.matching.resolve({
  entityType: 'sku',
  identifiers: [{ type: 'sku', value: 'SHOP-9912', sourceSystem: 'shopify' }],
});

// { confidence, score, match, candidates, needsReview }

import { verifyWebhookAsync } from '@logistics/sdk/webhooks';

app.post('/webhooks/logistics', async (req, res) => {
  try {
    const event = await verifyWebhookAsync({
      payload: req.rawBody,                       // raw string or Uint8Array
      signatureHeader: req.headers['x-signature'],
      secret: process.env.LOGISTICS_WEBHOOK_SECRET,
    });
    console.log(event.type, event.data);
    res.sendStatus(200);
  } catch {
    res.sendStatus(400);                          // bad signature or stale timestamp
  }
});

const client = new Logistics({ apiKey, webhookSecret: 'whsec_...' });

client.webhooks.on('shipment.eta_changed', (e) => notifyCustomer(e.data));
client.webhooks.on('vehicle.geofence_enter', (e) => markArrived(e.data));

client.webhooks.handle(req.headers['x-signature'], req.rawBody);

import { LogisticsError } from '@logistics/sdk';

try {
  await client.shipments.get('missing');
} catch (e) {
  if (e instanceof LogisticsError) {
    if (e.isNotFound) { /* 404 */ }
    if (e.isRateLimited) { /* 429, back off */ }
    console.log(e.code, e.status, e.retryable);
  }
}