Amazon Ads Refresh Tokens: 365 Tage Laufzeit seit dem 30. Juli, keine Erinnerung

Vor elf Tagen hat Amazon geändert, wie lange ein Refresh Token für die Advertising API gültig bleibt. Hat Ihre Integration am 1. August einen Advertiser autorisiert, funktioniert dieses Token am 01.08.2027 nicht mehr – ganz gleich, wie oft Sie es dazwischen einsetzen. Es gibt keine E-Mail, keinen Deprecation-Header, keinen Hinweis in der Console. Auffallen wird es allein Ihnen, und zwar genau in dem Moment, in dem ein nächtlicher Export leer zurückkommt. Dieser Artikel korrigiert zunächst ein weit verbreitetes falsches Datum und baut anschließend das Einzige, was Sie tatsächlich schützt: ein Token-Ledger mit einem Cron-Job.

1. Was sich geändert hat – und das Datum, das alle falsch angeben

Amazon hat die Änderung am 26.05.2026 angekündigt. In Kraft getreten ist sie am 30.07.2026. Refresh Tokens, die an oder nach diesem Datum ausgestellt werden, laufen 365 Tage nach dem Datum ab, an dem der Advertiser seinen Consent erteilt hat – nicht 365 Tage nach der Ausstellung des Tokens und auch nicht 365 Tage nach der letzten Nutzung.

Hartnäckig kursiert ein falsches Datum: der 30. Juni. Es steht in Forenbeiträgen, in Changelogs von Anbietern und in Suchmaschinen-Zusammenfassungen, die auf die Frage, seit wann Amazon Refresh Tokens ablaufen, selbstbewusst „30. Juni“ antworten. Das ist einen vollen Monat daneben. Wenn Sie ein Migrationsfenster auf Ende Juni gelegt oder einem Kunden gesagt haben, seine Tokens seien bereits abgedeckt, prüfen Sie Ihre Annahmen. Der korrekte Stichtag ist der 30.07.2026, und die ersten Massenabläufe fallen damit auf den Zeitraum ab dem 30.07.2027.

• Angekündigt: 26.05.2026.
• In Kraft: 30.07.2026, nicht 30. Juni.
• Laufzeit: 365 Tage ab dem Consent-Datum des Advertisers.
• Wiederherstellung nach Ablauf: ein frischer Consent des Advertisers über einen interaktiven Dialog. Einen stillen Weg zurück gibt es nicht.
• Benachrichtigung durch Amazon: keine.

2. Warum es nichts bringt, das Token zu benutzen

An diesem Punkt stolpern auch erfahrene Teams. In praktisch jedem OAuth-Setup, mit dem Sie bisher zu tun hatten, hat ein Refresh Token entweder gar kein Ablaufdatum oder ein gleitendes: Jeder Tausch gegen ein neues Access Token setzt den Idle-Timer zurück, sodass eine stündlich laufende Integration faktisch nie abläuft. Amazons Uhr gleitet nicht mit. Sie ist am Consent-Datum verankert und läuft unabhängig vom Traffic auf null. Eine Pipeline, die ein Jahr lang alle 55 Minuten sauber refresht hat, fällt an Tag 366 genauso aus wie eine, die seit Tag eins brachliegt.

Der Fehlerfall ist deshalb leise und tritt verzögert ein. Ihr Monitoring sieht bis unmittelbar an die Grenze heran eine gesunde Integration, dann einen Refresh-Call, der kein Access Token mehr zurückgibt – und die Lösung ist weder ein Retry noch ein Redeploy. Jemand beim Advertiser muss sich erneut durch einen Consent-Dialog klicken. An einem Samstag, für einen Kunden in einer anderen Zeitzone, ist das keine Wiederherstellung in fünf Minuten.

Im selben Atemzug erwähnenswert, weil es dieselben Codebasen trifft: Sechs alte Endpunkte des Account Managements sind seit Juli 2026 für neue Nutzung gesperrt und liefern ab Juli 2027 HTTP 404. Ihre Nachfolger sind seit dem 04.06.2026 allgemein verfügbar. Planen Sie diese Migration in dasselbe Quartal wie Ihre Consent-Erneuerungen.

3. Ein Token-Ledger auf Ihrer Seite

Amazon wird Ihnen nicht mitteilen, wann ein Token stirbt. Speichern Sie deshalb die einzige Tatsache, auf die es ankommt – das Consent-Datum – und leiten Sie alles Übrige daraus ab. Eine Tabelle pro Environment genügt. Die Spalte mit dem Ablaufdatum ist generiert und kann dadurch nie aus dem Tritt mit dem Consent-Datum geraten.

CREATE TABLE amazon_ads_token_ledger (
    advertiser_id   text PRIMARY KEY,
    account_name    text NOT NULL,
    region          text NOT NULL CHECK (region IN ('na', 'eu', 'fe')),
    consent_date    date NOT NULL,
    token_issued_at timestamptz NOT NULL,
    expires_on      date GENERATED ALWAYS AS (consent_date + 365) STORED,
    last_refresh_ok timestamptz,
    owner_email     text NOT NULL,
    status          text NOT NULL DEFAULT 'active'
);

CREATE INDEX ON amazon_ads_token_ledger (expires_on) WHERE status = 'active';

Befüllen Sie die Tabelle einmalig, notfalls von Hand. Tragen Sie für jeden Advertiser, den Sie am oder nach dem 30.07.2026 onboardet haben, das Consent-Datum aus Ihren Onboarding-Unterlagen ein. Für ältere Tokens erfassen Sie das Datum trotzdem und setzen status = 'legacy': Sobald ein solcher Advertiser aus irgendeinem Grund erneut seinen Consent gibt, gilt für das Ersatz-Token die neue Regel – und dann soll die Zeile bereits stehen.

4. Das Prüfskript und die Crontab-Zeile

Das Skript gibt nichts aus, solange alles in Ordnung ist – Cron bleibt also still. Ab 60 Tagen beginnt es, Ihnen zu mailen, und es beendet sich mit einem Exit-Code ungleich null, sobald wirklich etwas abgelaufen ist, damit ein Wrapper oder Ihr Monitoring darauf alarmieren kann.

#!/usr/bin/env python3
"""Warnt vor Amazon Ads Consents, die sich ihrer 365-Tage-Grenze naehern."""
import sys
from datetime import date
import psycopg

DSN = "postgresql:///ops"
WARN_DAYS = 60

QUERY = """
SELECT advertiser_id, account_name, region, consent_date, expires_on,
       expires_on - CURRENT_DATE AS days_left, owner_email
FROM amazon_ads_token_ledger
WHERE status = 'active'
  AND expires_on - CURRENT_DATE <= %s
ORDER BY days_left
"""

def main() -> int:
    with psycopg.connect(DSN) as conn:
        rows = conn.execute(QUERY, (WARN_DAYS,)).fetchall()
    if not rows:
        return 0
    print(f"Amazon Ads re-consent needed, checked {date.today()}:")
    for aid, name, region, consent, expires, days, owner in rows:
        state = "EXPIRED" if days < 0 else f"{days} days left"
        print(f"  {aid}  {name}  [{region}]  consent={consent}  "
              f"expires={expires}  {state}  owner={owner}")
    return 1 if any(r[5] < 0 for r in rows) else 0

if __name__ == "__main__":
    sys.exit(main())

# crontab -e  (als Service-User ausfuehren, dem die ops-Datenbankrolle gehoert)
MAILTO=ads-ops@example.com
17 6 * * * /usr/bin/python3 /opt/ads/token_ledger_check.py

Die 60 Tage sind nicht willkürlich gewählt. Ein erneuter Consent ist ein menschlicher Prozess: Sie müssen die richtige Person beim Advertiser erreichen, diese muss jemanden mit Freigabebefugnis auftreiben, und diese Kette dauert routinemäßig vier bis sechs Wochen. Aktualisieren Sie last_refresh_ok zusätzlich aus Ihrem Refresh-Job heraus, damit auch eine völlig andere Störung in derselben Tabelle auftaucht.

5. Fazit

Sie haben ein Ledger gebaut, das das Consent-Datum jedes Advertisers festhält und das Ablaufdatum als Consent plus 365 Tage in der Datenbank statt im Anwendungscode ableitet, dazu einen Cron-Job, der Ihnen zwei Monate vor dem Ausfall zu mailen beginnt. Gesamter Fußabdruck: eine Tabelle, ein Index, vierzig Zeilen Python, ein Crontab-Eintrag. Das ersetzt eine Klasse von Ausfällen, für die es kein Error Budget gibt, weil der Weg zurück ein Telefonat ist und kein Deployment.

Zwei Dinge zum Mitnehmen. Der Stichtag ist der 30.07.2026 und nicht der 30. Juni, was auch immer eine Suchergebnis-Zusammenfassung behauptet; Tokens, die ab diesem Tag ausgestellt werden, laufen also ab dem 30.07.2027 aus. Und die Nutzung verlängert die Laufzeit nicht – deshalb kann eine Integration, die heute vollkommen gesund aussieht, elf Monate vor dem harten Stopp stehen. Amazon dokumentiert das Verhalten unter access tokens in den Amazon Advertising API Guides; behandeln Sie diese Seite als Quelle der Wahrheit und Ihr Ledger als den Wecker, den Amazon nicht mitliefert.