for Digital Nomads Toggl in 2026: A Complete Guide

import os
import requests
import pytz
from datetime import datetime, timedelta
from dotenv import load_dotenv
import time

# Load Toggl API credentials from .env file
load_dotenv()

TOGGL_API_KEY = os.getenv("TOGGL_API_KEY")
TOGGL_WORKSPACE_ID = os.getenv("TOGGL_WORKSPACE_ID")
# Toggl API v3 base URL as of 2026
TOGGL_API_BASE = "https://api.track.toggl.com/api/v3"

def validate_env_vars():
    """Check that required environment variables are set, raise error if missing"""
    required_vars = ["TOGGL_API_KEY", "TOGGL_WORKSPACE_ID"]
    missing = [var for var in required_vars if not os.getenv(var)]
    if missing:
        raise ValueError(f"Missing required environment variables: {', '.join(missing)}")

def create_time_entry(project_id: str, description: str, duration_seconds: int, start_time: datetime) -> dict:
    """
    Create a Toggl time entry via API v3.
    Args:
        project_id: Toggl project ID to associate entry with
        description: Entry description (e.g., git commit message)
        duration_seconds: Duration of entry in seconds (negative for running entries)
        start_time: Datetime object for entry start time (timezone-aware)
    Returns:
        Created time entry dict from API response
    """
    url = f"{TOGGL_API_BASE}/workspaces/{TOGGL_WORKSPACE_ID}/time_entries"
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Basic {TOGGL_API_KEY}:api_token"
    }
    # Format start time to ISO 8601 with timezone offset, required by Toggl v3
    start_iso = start_time.isoformat()
    payload = {
        "project_id": project_id,
        "description": description,
        "start": start_iso,
        "duration": duration_seconds,
        "created_with": "toggl-nomad-git-automation"
    }

    try:
        response = requests.post(url, json=payload, headers=headers, timeout=10)
        # Handle rate limiting: Toggl v3 allows 1000 requests per hour per workspace
        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Retrying after {retry_after} seconds.")
            time.sleep(retry_after)
            return create_time_entry(project_id, description, duration_seconds, start_time)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.Timeout:
        print("API request timed out. Check network connectivity (common for nomads in remote areas).")
        raise
    except requests.exceptions.HTTPError as e:
        print(f"HTTP error creating time entry: {e.response.status_code} - {e.response.text}")
        raise
    except Exception as e:
        print(f"Unexpected error creating time entry: {str(e)}")
        raise

def sync_git_commits_to_toggl(repo_path: str, project_id: str, days_back: int = 1):
    """
    Sync recent git commits to Toggl as time entries.
    Args:
        repo_path: Path to local git repository
        project_id: Toggl project ID to log commits to
        days_back: Number of days to look back for commits
    """
    import subprocess
    # Calculate start time for commit lookup (timezone-aware UTC)
    start_time = datetime.now(pytz.utc) - timedelta(days=days_back)
    # Git log format: %H (hash), %s (subject), %aI (author date ISO 8601), %an (author name)
    git_log_cmd = [
        "git", "-C", repo_path, "log",
        f"--since={start_time.isoformat()}",
        "--format=%H|%s|%aI|%an"
    ]

    try:
        result = subprocess.run(git_log_cmd, capture_output=True, text=True, check=True)
        commits = result.stdout.strip().split("\n") if result.stdout.strip() else []
        print(f"Found {len(commits)} commits in last {days_back} day(s)")

        for commit in commits:
            if not commit:
                continue
            commit_hash, subject, author_iso, author_name = commit.split("|", 3)
            # Parse commit time, make timezone-aware
            commit_time = datetime.fromisoformat(author_iso)
            # Estimate commit duration: 15 minutes per commit (adjust based on your workflow)
            commit_duration = 15 * 60  # 900 seconds
            entry_desc = f"[{commit_hash[:7]}] {subject}"
            try:
                entry = create_time_entry(
                    project_id=project_id,
                    description=entry_desc,
                    duration_seconds=commit_duration,
                    start_time=commit_time
                )
                print(f"Created Toggl entry {entry['id']} for commit {commit_hash[:7]}")
            except Exception as e:
                print(f"Failed to create entry for commit {commit_hash[:7]}: {str(e)}")
                continue
    except subprocess.CalledProcessError as e:
        print(f"Git command failed: {e.stderr}")
        raise

if __name__ == "__main__":
    validate_env_vars()
    # Example config: replace with your own values
    REPO_PATH = os.getenv("GIT_REPO_PATH", "./my-nomad-project")
    PROJECT_ID = os.getenv("TOGGL_PROJECT_ID", "12345678")
    sync_git_commits_to_toggl(REPO_PATH, PROJECT_ID, days_back=1)

const axios = require('axios');
const dotenv = require('dotenv');
const fs = require('fs');
const path = require('path');
const { DateTime } = require('luxon');

// Load environment variables from .env file
dotenv.config();

const TOGGL_API_KEY = process.env.TOGGL_API_KEY;
const TOGGL_WORKSPACE_ID = process.env.TOGGL_WORKSPACE_ID;
const TOGGL_API_BASE = 'https://api.track.toggl.com/api/v3';
// Report output directory, create if not exists
const REPORT_DIR = path.join(__dirname, 'toggl-reports');

/**
 * Validate required environment variables are set
 * @throws {Error} If required vars are missing
 */
function validateEnv() {
    const required = ['TOGGL_API_KEY', 'TOGGL_WORKSPACE_ID'];
    const missing = required.filter(varName => !process.env[varName]);
    if (missing.length > 0) {
        throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
    }
}

/**
 * Fetch detailed time entries for a given date range from Toggl API v3
 * @param {DateTime} start - Start date (inclusive, timezone-aware)
 * @param {DateTime} end - End date (inclusive, timezone-aware)
 * @returns {Promise} Array of time entry objects
 */
async function fetchTimeEntries(start, end) {
    const url = `${TOGGL_API_BASE}/workspaces/${TOGGL_WORKSPACE_ID}/time_entries`;
    const auth = Buffer.from(`${TOGGL_API_KEY}:api_token`).toString('base64');
    const headers = {
        'Authorization': `Basic ${auth}`,
        'Content-Type': 'application/json'
    };
    // Toggl v3 uses start_date and end_date query params in ISO 8601
    const params = {
        start_date: start.toISO(),
        end_date: end.toISO(),
        per_page: 1000 // Max per page for v3
    };

    try {
        const response = await axios.get(url, { headers, params, timeout: 15000 });
        // Handle rate limiting
        if (response.status === 429) {
            const retryAfter = parseInt(response.headers['retry-after']) || 60;
            console.log(`Rate limited. Retrying after ${retryAfter} seconds.`);
            await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
            return fetchTimeEntries(start, end);
        }
        if (response.status !== 200) {
            throw new Error(`Failed to fetch entries: ${response.status} ${response.statusText}`);
        }
        return response.data;
    } catch (error) {
        if (error.response) {
            console.error(`API error: ${error.response.status} - ${JSON.stringify(error.response.data)}`);
        } else {
            console.error(`Request error: ${error.message}`);
        }
        throw error;
    }
}

/**
 * Generate a CSV report for tax filing, grouped by jurisdiction (time zone)
 * @param {Array} entries - Toggl time entries
 * @param {string} outputPath - Path to write CSV file
 */
function generateTaxReport(entries, outputPath) {
    // CSV header: Date, Start Time (UTC), Duration (hours), Description, Time Zone, Jurisdiction
    const csvRows = [
        'Date,Start Time (UTC),Duration (hours),Description,Time Zone,Jurisdiction'
    ];

    entries.forEach(entry => {
        const start = DateTime.fromISO(entry.start, { zone: 'utc' });
        const durationHours = Math.abs(entry.duration) / 3600; // duration is negative for running entries
        const timeZone = entry.timezone || 'UTC';
        // Simple jurisdiction mapping: replace with your own tax jurisdictions
        const jurisdictionMap = {
            'Europe/Madrid': 'Spain',
            'Asia/Bangkok': 'Thailand',
            'America/New_York': 'USA',
            'UTC': 'Unknown'
        };
        const jurisdiction = jurisdictionMap[timeZone] || 'Other';

        csvRows.push(
            `${start.toFormat('yyyy-MM-dd')},` +
            `${start.toFormat('HH:mm:ss')},` +
            `${durationHours.toFixed(2)},` +
            `"${entry.description.replace(/"/g, '""')}",` + // Escape quotes in CSV
            `${timeZone},` +
            `${jurisdiction}`
        );
    });

    fs.writeFileSync(outputPath, csvRows.join('\n'), 'utf8');
    console.log(`Tax report written to ${outputPath}`);
}

/**
 * Main execution function
 */
async function main() {
    validateEnv();

    // Create report directory if it doesn't exist
    if (!fs.existsSync(REPORT_DIR)) {
        fs.mkdirSync(REPORT_DIR, { recursive: true });
    }

    // Generate report for Q4 2025 (adjust for your tax period)
    const start = DateTime.now().minus({ months: 3 }).startOf('quarter');
    const end = DateTime.now().minus({ months: 3 }).endOf('quarter');
    console.log(`Fetching entries from ${start.toISO()} to ${end.toISO()}`);

    try {
        const entries = await fetchTimeEntries(start, end);
        console.log(`Fetched ${entries.length} time entries`);
        const outputPath = path.join(REPORT_DIR, `toggl-tax-report-${start.toFormat('yyyy-QQ')}.csv`);
        generateTaxReport(entries, outputPath);
    } catch (error) {
        console.error('Failed to generate tax report:', error.message);
        process.exit(1);
    }
}

// Run main function if script is executed directly
if (require.main === module) {
    main();
}

package main

import (
    "bufio"
    "context"
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os"
    "os/signal"
    "sync"
    "time"

    "github.com/joho/godotenv"
    "github.com/mitchellh/go-homedir"
)

const (
    togglAPIBase = "https://api.track.toggl.com/api/v3"
    offlineQueueFile = "~/.toggl-nomad/offline-queue.json"
    syncInterval = 5 * time.Minute
)

// TimeEntry represents a Toggl time entry for offline queuing
type TimeEntry struct {
    ID          string `json:"id,omitempty"`
    ProjectID   string `json:"project_id"`
    Description string `json:"description"`
    Start       string `json:"start"`
    Duration    int    `json:"duration"`
    Timezone    string `json:"timezone"`
    Synced      bool   `json:"synced"`
}

// TogglClient wraps Toggl API interactions
type TogglClient struct {
    apiKey      string
    workspaceID string
    httpClient  *http.Client
}

func NewTogglClient(apiKey, workspaceID string) *TogglClient {
    return &TogglClient{
        apiKey:      apiKey,
        workspaceID: workspaceID,
        httpClient:  &http.Client{Timeout: 10 * time.Second},
    }
}

// Load offline queue from disk
func loadOfflineQueue() ([]TimeEntry, error) {
    path, err := homedir.Expand(offlineQueueFile)
    if err != nil {
        return nil, fmt.Errorf("failed to expand offline queue path: %w", err)
    }
    data, err := os.ReadFile(path)
    if err != nil {
        if os.IsNotExist(err) {
            return []TimeEntry{}, nil
        }
        return nil, fmt.Errorf("failed to read offline queue: %w", err)
    }
    var entries []TimeEntry
    if err := json.Unmarshal(data, &entries); err != nil {
        return nil, fmt.Errorf("failed to unmarshal offline queue: %w", err)
    }
    return entries, nil
}

// Save offline queue to disk
func saveOfflineQueue(entries []TimeEntry) error {
    path, err := homedir.Expand(offlineQueueFile)
    if err != nil {
        return fmt.Errorf("failed to expand offline queue path: %w", err)
    }
    // Create directory if not exists
    dir := path[:len(path)-len("offline-queue.json")]
    if err := os.MkdirAll(dir, 0755); err != nil {
        return fmt.Errorf("failed to create offline queue directory: %w", err)
    }
    data, err := json.MarshalIndent(entries, "", "  ")
    if err != nil {
        return fmt.Errorf("failed to marshal offline queue: %w", err)
    }
    if err := os.WriteFile(path, data, 0644); err != nil {
        return fmt.Errorf("failed to write offline queue: %w", err)
    }
    return nil
}

// SyncOfflineEntries pushes queued offline entries to Toggl API
func (c *TogglClient) SyncOfflineEntries(ctx context.Context) error {
    entries, err := loadOfflineQueue()
    if err != nil {
        return fmt.Errorf("failed to load offline queue: %w", err)
    }
    if len(entries) == 0 {
        log.Println("No offline entries to sync")
        return nil
    }

    var wg sync.WaitGroup
    errChan := make(chan error, len(entries))
    syncedCount := 0

    for i := range entries {
        if entries[i].Synced {
            continue
        }
        wg.Add(1)
        go func(idx int) {
            defer wg.Done()
            entry := entries[idx]
            url := fmt.Sprintf("%s/workspaces/%s/time_entries", togglAPIBase, c.workspaceID)
            payload, _ := json.Marshal(entry)
            req, _ := http.NewRequestWithContext(ctx, "POST", url, bufio.NewReader(payload))
            req.Header.Set("Content-Type", "application/json")
            req.Header.Set("Authorization", fmt.Sprintf("Basic %s:api_token", c.apiKey))

            resp, err := c.httpClient.Do(req)
            if err != nil {
                errChan <- fmt.Errorf("failed to sync entry %s: %w", entry.ID, err)
                return
            }
            defer resp.Body.Close()

            if resp.StatusCode == 429 {
                // Rate limited, retry later
                log.Printf("Rate limited syncing entry %s, will retry next interval", entry.ID)
                return
            }
            if resp.StatusCode >= 400 {
                errChan <- fmt.Errorf("API error syncing entry %s: %d", entry.ID, resp.StatusCode)
                return
            }

            entries[idx].Synced = true
            syncedCount++
            log.Printf("Synced offline entry %s", entry.ID)
        }(i)
    }

    wg.Wait()
    close(errChan)

    // Save updated queue
    if err := saveOfflineQueue(entries); err != nil {
        return fmt.Errorf("failed to save offline queue after sync: %w", err)
    }

    for err := range errChan {
        log.Printf("Sync error: %v", err)
    }

    log.Printf("Synced %d/%d offline entries", syncedCount, len(entries))
    return nil
}

func main() {
    // Load .env file
    if err := godotenv.Load(); err != nil {
        log.Printf("Warning: no .env file found: %v", err)
    }

    apiKey := os.Getenv("TOGGL_API_KEY")
    workspaceID := os.Getenv("TOGGL_WORKSPACE_ID")
    if apiKey == "" || workspaceID == "" {
        log.Fatal("TOGGL_API_KEY and TOGGL_WORKSPACE_ID must be set")
    }

    client := NewTogglClient(apiKey, workspaceID)
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel()

    // Handle OS signals for graceful shutdown
    sigChan := make(chan os.Signal, 1)
    signal.Notify(sigChan, os.Interrupt)
    go func() {
        <-sigChan
        log.Println("Shutting down offline sync daemon...")
        cancel()
    }()

    // Run sync on interval
    ticker := time.NewTicker(syncInterval)
    defer ticker.Stop()

    log.Println("Starting Toggl offline sync daemon...")
    for {
        select {
        case <-ticker.C:
            if err := client.SyncOfflineEntries(ctx); err != nil {
                log.Printf("Sync cycle failed: %v", err)
            }
        case <-ctx.Done():
            log.Println("Daemon stopped")
            return
        }
    }
}

import requests
import pytz
from dotenv import load_dotenv
load_dotenv()
def update_toggl_timezone():
    ip_tz = pytz.timezone(requests.get("https://ipapi.co/timezone/").text.strip())
    requests.patch(f"https://api.track.toggl.com/api/v3/me", 
        headers={"Authorization": f"Basic {os.getenv('TOGGL_API_KEY')}:api_token"},
        json={"timezone": str(ip_tz)})

async function batchCreateEntries(entries) {
    const url = `https://api.track.toggl.com/api/v3/workspaces/${process.env.TOGGL_WORKSPACE_ID}/time_entries/batch`;
    return axios.post(url, entries, {
        headers: {
            "Authorization": `Basic ${process.env.TOGGL_API_KEY}:api_token`,
            "Idempotency-Key": require("crypto").randomUUID()
        }
    });
}

curl -X POST "https://api.track.toggl.com/api/v3/workspaces/$TOGGL_WORKSPACE_ID/audits" \
  -H "Authorization: Basic $TOGGL_API_KEY:api_token" \
  -H "Content-Type: application/json" \
  -d '{"start_date": "2026-01-01T00:00:00Z", "end_date": "2026-01-31T23:59:59Z"}'

toggl-nomad-2026-workflows/
├── python/
│   ├── git-commit-sync.py       # Code Example 1: Git commit to Toggl syncing
│   ├── requirements.txt         # Python dependencies (requests, pytz, python-dotenv)
│   └── .env.example             # Example environment variables
├── nodejs/
│   ├── tax-report-generator.js  # Code Example 2: Automated tax reporting
│   ├── package.json             # Node.js dependencies (axios, dotenv, luxon)
│   └── .env.example
├── go/
│   ├── offline-sync-daemon.go   # Code Example 3: Offline sync daemon
│   ├── go.mod                    # Go module dependencies
│   └── .env.example
├── github-actions/
│   └── toggl-pr-sync.yml        # GitHub Action for PR time entry creation
├── benchmarks/
│   ├── api-latency-2026.csv      # API latency benchmarks for Toggl v2 vs v3
│   └── cost-savings-2026.csv     # Cost savings data from case study
├── LICENSE                       # MIT License
└── README.md                     # Full setup instructions