Test a Time-Based API Tariff Across a DST Change

AI and affiliation disclosure: An AI agent prepared this technical article for TokenPeak. The code is a local teaching fixture adapted from a dated schedule, not a production billing implementation. Its five boundary assertions were rerun locally on November 3, 2026; no paid request or account charge was tested.

A time-based tariff has at least two clocks: the clock used by the billing rule and the clock shown to the person reading an estimate. Mixing them can assign a request to the wrong band even when the displayed time looks reasonable.

The exercise below accepts an aware UTC request-start instant. It selects a band in the rule's timezone and separately renders the same instant in a viewer's timezone. There are no prices, account credentials, or network calls in the resolver.

Freeze the rule before testing the clock

This fixture preserves the minute boundaries from a public schedule captured on October 23, 2026 at 09:39:32 UTC. Its billing zone is Asia/Shanghai; D and R are simply two band labels. It uses request start as the selection basis and half-open intervals: the start is included, the end is excluded.

The lower-band periods are:

Billing-zone days	Included intervals
Monday–Friday	00:00–09:00, 12:00–14:00, 18:00–24:00
Saturday–Sunday	00:00–08:59, 09:00–24:00

The weekend 08:59–09:00 gap is intentional in this frozen fixture because it exists in the source snapshot. Do not silently change 539 to 540 because the schedule looks unusual. Whether a production issuer intended that gap is a separate question from whether a resolver preserves it.

Here is the complete example. It needs Python with IANA timezone data available; see the Python zoneinfo documentation for the system database and tzdata fallback, including Windows environments.

from datetime import datetime, timedelta
from zoneinfo import ZoneInfo

# Frozen teaching fixture: Sunday=0, Saturday=6; [start, end).
RULE = {
    "id": "tariff-20261023-093932Z-v1",
    "zone": "Asia/Shanghai",
    "basis": "request_start",
    "low": [
        ([0, 6], 0, 539), ([0, 6], 540, 1440),
        ([1, 2, 3, 4, 5], 0, 540),
        ([1, 2, 3, 4, 5], 720, 840),
        ([1, 2, 3, 4, 5], 1080, 1440),
    ],
}


def resolve(start_utc, viewer_zone):
    if start_utc.tzinfo is None or start_utc.utcoffset() != timedelta(0):
        raise ValueError("Supply an aware UTC request-start instant")
    billing = start_utc.astimezone(ZoneInfo(RULE["zone"]))
    day = (billing.weekday() + 1) % 7  # Python Monday=0 -> Sunday=0
    minute = billing.hour * 60 + billing.minute
    low = any(day in days and begin <= minute < end
              for days, begin, end in RULE["low"])
    return {
        "rule_id": RULE["id"],
        "basis": RULE["basis"],
        "tier": "D" if low else "R",
        "start_utc": start_utc.isoformat(),
        "billing_local": billing.isoformat(),
        "viewer_local": start_utc.astimezone(ZoneInfo(viewer_zone)).isoformat(),
    }


if __name__ == "__main__":
    cases = [
        ("2026-10-23T09:59:59+00:00", "Europe/London", "R"),
        ("2026-10-23T10:00:00+00:00", "Europe/London", "D"),
        ("2026-10-24T00:58:59+00:00", "America/Los_Angeles", "D"),
        ("2026-10-24T00:59:00+00:00", "America/Los_Angeles", "R"),
        ("2026-10-24T01:00:00+00:00", "America/Los_Angeles", "D"),
    ]
    for timestamp, zone, expected in cases:
        result = resolve(datetime.fromisoformat(timestamp), zone)
        assert result["tier"] == expected, result
    print("5 frozen-fixture cases passed; no billing API was called.")

Save it as tariff_example.py and run python tariff_example.py without optimization flags, because those flags can disable assertions. During preparation, this exact block passed its five cases on Python 3.12.14 with the tzdata 2026.5 package. That is evidence about the local fixture only.

Test both sides of a transition

At 2026-10-23 10:00 UTC, London displays 11:00 with offset +01:00. At 2026-10-26 10:00 UTC, it displays 10:00 with offset +00:00. Both instants map to 18:00 in the billing zone and select D in this fixture. A fixed “London is UTC+1” assumption would mislabel the second date.

The Los Angeles Friday boundary catches another mistake. At 2026-10-24 00:59 UTC, the viewer sees Friday 17:59 at -07:00, but the billing zone is already Saturday 08:59. The resolver must use Saturday's rule, including its one-minute gap. At 01:00 UTC it reaches Saturday 09:00 and returns to D.

After the US fallback, 2026-11-03 01:00 UTC displays Monday November 2 at 17:00 in Los Angeles, offset -08:00. It maps to Tuesday 09:00 in the billing zone, where the weekday band is R. Neither the viewer's weekday nor a fixed offset is a substitute for the conversion.

Preserve repeated hours and event meaning

During London's October 25 fallback, 00:30 UTC and 01:30 UTC both display 01:30 locally, but with different offsets. Keep the UTC instant and offset in any diagnostic record. Starting with UTC also avoids having to guess which occurrence a naive local 01:30 means.

The event itself matters just as much. A request starting at 09:59:59 UTC and finishing at 10:00:01 UTC crosses a band boundary on October 23. This fixture selects by start time. Replacing that input with completion time would implement a different contract. A real service might define receipt or completion instead; its actual rule must decide.

Before adapting this exercise, bind the schedule to a versioned source, retain its timezone and interval convention, and test exact endpoints, repeated hours, weekday conversion, and invalid timestamps. A historical fixture has no authority to choose a future invoice's rate. It gives you reproducible clock behavior while the live rule, eligibility, exceptions, and settlement remain separate evidence.