How to build a countdown timer in Flutter

Your backend endpoint

// Your backend, in whatever language. The app calls THIS.
// Node/Express shown; the shape is the same everywhere.
app.get("/api/countdown/:id", async (req, res) => {
  const upstream = await fetch(
    `https://countdownshare.com/api/v1/timers/${req.params.id}/status`,
    {
      headers: { Authorization: `Bearer ${process.env.COUNTDOWNSHARE_API_KEY}` },
      cache: "no-store",
    },
  );

  if (!upstream.ok) return res.status(502).json({ error: "unavailable" });

  const { data } = await upstream.json();

  // Return only what the screen needs.
  res.json({
    remaining_seconds: data.remaining.total_seconds,
    server_time: data.server_time,
    ended: data.ended,
  });
});

lib/countdown/countdown_controller.dart

// lib/countdown/countdown_controller.dart
import 'dart:async';
import 'package:flutter/widgets.dart';

/// Ticks locally, counts against the server.
///
/// The device clock is compared to the server's once, and the
/// offset is subtracted on every tick — so a phone set an hour
/// forward still shows the correct remaining time.
class CountdownController extends ChangeNotifier with WidgetsBindingObserver {
  CountdownController({required this.api, required this.timerId}) {
    WidgetsBinding.instance.addObserver(this);
    _load();
  }

  final CountdownApi api;
  final String timerId;

  Duration _remaining = Duration.zero;
  Duration _skew = Duration.zero;
  DateTime? _endsAt;
  Timer? _ticker;
  bool _loading = true;

  Duration get remaining => _remaining;
  bool get loading => _loading;
  bool get ended => !_loading && _remaining == Duration.zero;

  Future<void> _load() async {
    try {
      final status = await api.status(timerId);

      // Measure the gap between this device's clock and ours.
      _skew = DateTime.now().difference(status.serverTime);
      _endsAt = DateTime.now()
          .subtract(_skew)
          .add(Duration(seconds: status.remainingSeconds));

      _loading = false;
      _tick();
      _ticker?.cancel();
      _ticker = Timer.periodic(const Duration(seconds: 1), (_) => _tick());
    } catch (_) {
      _loading = false;
      notifyListeners();
    }
  }

  void _tick() {
    final endsAt = _endsAt;
    if (endsAt == null) return;

    final now = DateTime.now().subtract(_skew);
    final left = endsAt.difference(now);

    _remaining = left.isNegative ? Duration.zero : left;
    if (_remaining == Duration.zero) _ticker?.cancel();

    notifyListeners();
  }

  /// A suspended app resumes with a stale value. Re-read rather
  /// than trusting a timer that was frozen by the OS.
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.resumed) _load();
  }

  @override
  void dispose() {
    _ticker?.cancel();
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }
}

lib/countdown/countdown_text.dart

// lib/countdown/countdown_text.dart
import 'package:flutter/material.dart';

class CountdownText extends StatelessWidget {
  const CountdownText({super.key, required this.controller});

  final CountdownController controller;

  @override
  Widget build(BuildContext context) {
    return AnimatedBuilder(
      animation: controller,
      builder: (context, _) {
        if (controller.loading) {
          return const Text('--:--:--');
        }
        if (controller.ended) {
          return const Text('This offer has closed');
        }

        final d = controller.remaining;
        final hours = d.inHours;
        final minutes = d.inMinutes.remainder(60);
        final seconds = d.inSeconds.remainder(60);

        return Semantics(
          liveRegion: true,
          label: '$hours hours $minutes minutes remaining',
          child: Text(
            '${hours.toString().padLeft(2, '0')}:'
            '${minutes.toString().padLeft(2, '0')}:'
            '${seconds.toString().padLeft(2, '0')}',
            style: Theme.of(context).textTheme.headlineMedium,
          ),
        );
      },
    );
  }
}