Shipments Domain

Shipments API

Networks and shipment orchestration APIs for allocation, pricing, and execution across the Niyantha backend.

Base Path

https://api.niyantha.in/api/v1/session

Authentication

Authorization: Bearer <token>

Create networks that define pricing and constraints, then create shipments that the platform can allocate and track. These same primitives are available in S2S for partner backends.

POST/networks

Create a logistics network with pricing, constraints, and fulfillment configuration.

Bearer Token

Sample Request

{
  "name": "TMS Karnataka Last Mile",
  "group_key": "tms",
  "service_types": ["goods"],
  "location_id": 81,
  "pricing": {
    "base_fare": 40,
    "base_distance_m": 3000,
    "increment_fare": 12,
    "increment_distance_m": 1000
  },
  "constraints": {
    "max_distance_m": 25000,
    "max_matching_distance_m": 5000,
    "fair_allocation_radius_m": 1000,
    "max_weight_kg": 120,
    "allowed_vehicle_types": ["bike", "scooter", "rikshaw"]
  },
  "scope": {
    "type": "state",
    "value": "Karnataka",
    "country": "India",
    "state": "Karnataka",
    "whitelabel_scope": "district",
    "whitelabel_values": ["Bengaluru Urban", "Mysuru", "Udupi"]
  },
  "fulfillment": {
    "allow_split_shipment": true,
    "max_tasks_per_shipment": 3
  }
}

Sample Response

{
  "id": 145,
  "name": "TMS Karnataka Last Mile",
  "account_id": 42,
  "group_key": "tms",
  "service_types": ["goods"],
  "location_id": 81,
  "latitude": 12.9716,
  "longitude": 77.5946,
  "pricing": {
    "base_fare": 40,
    "base_distance_m": 3000,
    "increment_fare": 12,
    "increment_distance_m": 1000
  },
  "constraints": {
    "max_distance_m": 25000,
    "max_matching_distance_m": 5000,
    "fair_allocation_radius_m": 1000,
    "max_weight_kg": 120,
    "allowed_vehicle_types": ["bike", "scooter", "rikshaw"]
  },
  "scope": {
    "type": "state",
    "value": "Karnataka",
    "country": "India",
    "state": "Karnataka",
    "whitelabel_scope": "district",
    "whitelabel_values": ["Bengaluru Urban", "Mysuru", "Udupi"]
  },
  "fulfillment": {
    "allow_split_shipment": true,
    "max_tasks_per_shipment": 3
  },
  "status": "active",
  "created_at": 1772186400
}

POST/shipments

Create a shipment using a network's pricing and constraints.

Bearer Token

Sample Request

{
  "network_id": 101,
  "pickup_location_id": 66,
  "drop_location_id": 77,
  "total_weight_kg": 40,
  "packages": [
    {
      "package_type": "bag",
      "weight_kg": 20,
      "description": "Groceries",
      "items": [
        {
          "product_id": 501,
          "quantity": 2
        }
      ]
    }
  ]
}

Sample Response

{
  "id": 9001,
  "account_id": 1,
  "network_id": 101,
  "status": "created",
  "estimated_cost": 120,
  "total_capacity_required": 40,
  "capacity_remaining": 40
}

GET/shipments

Fetch shipments with network, status, location, and time filters.

Bearer Token

Query Parameters

Field	Type	Required	Description
page	int	No	1-based page index.
count	int	No	Page size.
network_id	uint	No	Filter by network.
status	string	No	Filter by single status.
status_in	string	No	Comma-separated status list.

Sample Response

{
  "items": [
    {
      "id": 9001,
      "network_id": 101,
      "status": "created",
      "estimated_cost": 120,
      "total_weight_kg": 40
    }
  ],
  "page": 1,
  "count": 1
}

GET/shipments/:id

Fetch a shipment with nested package details.

Bearer Token

Sample Response

{
  "id": 9001,
  "network_id": 101,
  "status": "created",
  "packages": [
    {
      "id": 1,
      "package_type": "bag",
      "weight_kg": 20,
      "items": [
        { "product_id": 501, "quantity": 2 }
      ]
    }
  ]
}

Notes

Distance calculations rely on Maps configuration in the backend, so production deployments should keep map credentials valid.

The same networks and shipments routes are exposed under /api/v1/s2s/accounts for API-key authenticated backends.