Der TVOD-Umsatzdatensatz enthält Verkaufsdaten auf Transaktionsebene für dein Prime Video Transactional Video on Demand (TVOD)-Geschäft. Jeder Datensatz steht für eine abgeschlossene Transaktion (Kauf oder Miete). Die Daten werden über die Slate Datasets API als Append-only-Changelog bereitgestellt. So hast du volle Flexibilität, benutzerdefinierte Analysen zu erstellen und auf deine Geschäftsanforderungen zugeschnittene Kennzahlen zu berechnen.
Wichtigste Vorteile
- Schnellere Erkenntnisse – Umsatzdaten werden mehrmals täglich in Batches bereitgestellt, wobei die meisten Transaktionen innerhalb von ~9 Stunden nach Abschluss verfügbar sind.
- Trennung von Kosten und Umsatz – Umsatzdaten werden in 4-Stunden-Batches bereitgestellt; Kosteninformationen (net_cogs) werden täglich aktualisiert, sodass du Umsatzdaten so schnell wie möglich erhältst.
- Konsistenz – Standardisierte Formatierung für alle Gebiete in einer einzigen Quelle.
- Vereinfachte Datenaufnahme – Append-only-Changelog-Modell mit einem einfachen Upsert-Muster für eine unkomplizierte, automatisierte Datenaufnahme.
- Granularität auf Transaktionsebene – Greife auf einzelne Daten auf Bestellebene zu, um benutzerdefinierte Analysen, Leistungsverfolgung auf Titelebene und interne Systemintegrationen zu ermöglichen.
- Flexible Integration – Integriere TVOD-Umsatzdaten in deine internen Systeme, Data Warehouses und BI-Tools.
Funktion |
Slate-Datensatz-API |
Art des Zugriffs |
Programmatisch (REST-API) |
Geeignet für |
Automatisierte Pipelines, Unternehmensberichte, benutzerdefinierte Analysen |
Authentifizierung |
Mit Amazon (LWA) -Sicherheitsprofil anmelden |
Datenformat |
CSV-Dateien (gzip-komprimiert) |
Erste Schritte
Voraussetzungen
- Aktive Prime Video TVOD-Partnerschaft
- Ein Sicherheitsprofil für Anmeldung mit Amazon (LWA)
- Eine bei deinem Content Account Manager (CAM) registrierte Client-ID
- Ein Autorisierungscode zum Anfordern eines Tokens
- Ein gültiges LWA-Authentifizierungstoken für alle API-Anfragen
Einrichtung der Authentifizierung
Um Datensätze abzurufen, musst du zunächst das Onboarding für die Datasets API Suite abschließen. Weitere Details findest du hier.
API-Endpunkte
Discovery-Endpunkte
Verwende diese Endpunkte, um deine Konto- und Vertrags-IDs programmgesteuert abzurufen:
Endpunkt |
Rückgabe |
|---|---|
GET /v2/accounts |
Liste der Slate-Konten, auf die du zugreifen kannst |
GET /v2/accounts/ {ACADIA_ID} |
Verfügbare Geschäftsbereiche (z. B. Channel, Transaktionen) |
GET /v2/accounts/{ACADIA_ID}/transactions |
Liste der TVOD-Vertrags-IDs für dein Konto |
GET /v2/accounts/{ACADIA_ID}/transactions/{CONTRACT_ID}/datasets |
Verfügbare Datensätze für einen Vertrag |
Datensatzdateien abrufen
Verwende diesen Endpunkt, um Links zu Transaktionsdatensatzdateien für deinen Vertrag abzurufen:curl -X GET \
-H "Authorization: Bearer Atza|auth_token" \
https://videocentral.amazon.com/api/v2/accounts/{ACADIA_ID}/transactions/{CONTRACT_ID}/\
datasets/transactions_event_log\
?startDateTime=YYYY-MM-DDThh:mm:ssZ\
&endDateTime=YYYY-MM-DDThh:mm:ssZ\
&offset=0&limit=1000
Anfrageparameter
Parameter |
Beschreibung |
|---|---|
ACADIA_ID |
Deine Slate-Konto-ID. Du findest sie über GET /v2/accounts. |
CONTRACT_ID |
Deine TVOD-Vertrags-ID. |
startDateTime |
Auf den Zeitpunkt des letzten Abrufs festlegen. Format: YYYY-MM-DDThh:mm:ssZ (UTC). |
endDateTime |
Auf die aktuelle Uhrzeit festlegen. Format: YYYY-MM-DDThh:mm:ssZ (UTC). |
Limit |
Maximal 1000 Links pro Seite. |
Dieser Endpunkt gibt Links zu herunterladbaren CSV-Dateien (gzip-komprimiert) zurück, die die Transaktionsprotokolle enthalten – nicht die Transaktionen selbst.
Seitennummerierung
Alle Antworten werden seitenweise ausgegeben. Verwende die folgenden Abfrageparameter, um durch die Ergebnisse zu navigieren:
Parameter |
Default |
Beschreibung |
|---|---|---|
limit |
10 |
Anzahl der pro Seite zurückgegebenen Dokumente. Maximal 1000. |
offset |
0 |
Anzahl der zu überspringenden Seiten. |
Alle seitenweise ausgegebenen Antworten enthalten die folgenden Felder:
Feld |
Beschreibung |
|---|---|
total |
Gesamtzahl der Dokumente über alle Seiten hinweg. |
next |
URL der nächsten Seite. Null auf der letzten Seite. |
Datenmodell
Schlüsselkonzepte
Konzept |
Beschreibung |
Transaktion |
Eine abgeschlossene Bestellung oder ein abgeschlossenes Ereignis (Kauf oder Miete). Jede Transaktion wird durch eine eindeutige order_item_id identifiziert. |
Changelog-Modell |
Daten können nur angehängt werden. Wenn sich die Attribute eines Datensatzes ändern (z. B. wenn Kosten hinzukommen), wird ein neuer Datensatz mit derselben order_item_id, aber einem neueren last_update_time_utc veröffentlicht. |
Primärschlüssel |
order_item_id ist die eindeutige Kennung für jede Transaktion. Führe die Deduplizierung immer anhand dieses Feldes durch. |
Kosten vs. Umsatz |
Umsatzdaten werden in 4-Stunden-Batches bereitgestellt. Costing (net_cogs) wird täglich aktualisiert. Sobald Kosten verfügbar sind, werden die Datensätze entsprechend aktualisiert. |
Aktualität der Daten
Attribut |
Ziel |
Lieferung von Verkaufsdaten |
Alle 4 Stunden (in Batches) |
Aktualisierung von Costing (net_cogs) |
Alle 24 Stunden |
End-to-End-Latenz |
~9 Stunden von der Transaktion bis zur Verfügbarkeit der Daten |
Datenaufbewahrung |
Maximal 2 Jahre |
Datengenauigkeit
Attribut |
Details |
Maßgebliche Datenquelle |
Gewinn- und Finanzberichte bleiben die maßgebliche Datenquelle für Auszahlungen und Kosten. |
Erwartete Abweichung |
Aufgrund von Unterschieden bei Datums- und Zeitangaben sowie bei der Aggregation können geringfügige Abweichungen gegenüber Finanz-/Tantiemenberichten auftreten. |
Geltungsbereich |
Abgeschlossene Bestellungen werden auf Transaktionsebene erfasst, um die Leistung nachzuverfolgen. Kein Ersatz für Finanz- oder Tantiemenberichte. |
Dieser Datensatz ist für eine schnellere, kontinuierliche Leistungsverfolgung konzipiert. Aufgrund von Unterschieden bei Datums- und Zeitangaben sowie bei der Aggregation sind geringfügige Abweichungen gegenüber Finanzberichten (z. B. Video ASIN Daily Level Summary) zu erwarten. Dies ist ein erwartetes Verhalten und kein Problem mit der Datenqualität.
Datendefinitionen
Kernfelder
In der folgenden Tabelle werden alle im Datensatz transactions_event_log verfügbaren Felder beschrieben:
Feldbezeichnung |
Typ |
Kann NULL sein |
Beschreibung |
Beispiel |
|---|---|---|---|---|
order_item_id |
STRING |
Nein |
Eindeutige Kennung für jede Transaktion. Primärschlüssel für die Deduplizierung. |
ABC123XYZ |
transaction_datetime_utc |
ZEITSTEMPEL |
Nein |
Transaktionszeit in UTC. |
2026-01-14T00:04:41.575 |
transaction_datetime_local |
ZEITSTEMPEL |
Nein |
Transaktionszeit in der lokalen Zeitzone. |
2026-01-14T01:04:41.575 |
pv_title_id |
STRING |
Nein |
Eindeutige Titel-ID. |
tt1234567 |
content_type |
STRING |
Nein |
Art des gekauften Inhalts. |
Film, TV-Folge, TV-Staffel |
purchase_type |
STRING |
Nein |
Kauf- oder Mietindikator. |
EST (Kauf), VOD (Miete) |
content_quality |
STRING |
Nein |
Stufe der Videoqualität. |
SD, HD, UHD |
Gebiet |
STRING |
Nein |
Gebietscode. |
US, GB, DE, JP, AU |
device_class |
STRING |
Ja |
Gerätekategorie. |
Fire TV, Mobilgerät, Web |
title_name |
STRING |
Nein |
Titelname. |
The Great Adventure |
Währung |
STRING |
Nein |
Währungscode nach ISO 4217. |
USD, EUR, JPY |
vendor_sku |
STRING |
Ja |
Vom Partner bereitgestellte SKU. |
WB-MOV-001 |
net_cogs |
DEZIMALWERT |
Ja |
Nettowarenkosten ohne Steuern. Wird täglich aktualisiert. Kann anfänglich NULL sein. |
4,99 |
net_revenue |
DEZIMALWERT |
Nein |
Nettoumsatz ohne Steuern. |
14,99 |
create_time_utc |
ZEITSTEMPEL |
Nein |
Erstellungszeit des Datensatzes in UTC. |
2026-01-14T01:39:06.619 |
last_update_time_utc |
ZEITSTEMPEL |
Nein |
Zeitpunkt der letzten Aktualisierung des Datensatzes. Wird für die Deduplizierungslogik verwendet. |
2026-01-14T01:39:06.619 |
Feldhinweise
Die folgenden Felder weisen wichtige Verhaltensmerkmale auf, die Partner kennen sollten:
Feld |
Berechnung/Logik |
Hinweise |
|---|---|---|
net_cogs |
Wird täglich aktualisiert |
Kann anfänglich als NULL oder 0 erscheinen; wird innerhalb von 24 Stunden aktualisiert, sobald die Kosten vorliegen. |
last_update_time_utc |
Neuester Zeitstempel hat Vorrang |
Wenn mehrere Datensätze mit derselben order_item_id vorhanden sind, behalte nur den Datensatz mit der neuesten last_update_time_utc bei. |
Gebiet |
Ein einziger Datensatz für alle Gebiete |
Keine separaten Dateien pro Gebiet; filtere bei Bedarf nach Gebietscode. |
purchase_type |
Feste Enum-Werte |
EST = Electronic Sell-Through (dauerhafter Kauf). VOD = zeitlich begrenzte Miete. |
Deduplizierung
Übersicht
Der Datensatz verwendet ein Changelog-Modell. Wenn ein Datensatz aktualisiert wird (z. B. wenn die Kalkulation eintrifft), wird eine neue Version mit derselben order_item_id und einer neueren last_update_time_utc veröffentlicht. Um genaue Daten zu gewährleisten, wende immer die Deduplizierungslogik an, bevor du Datensätze in dein Zielsystem schreibst.
Deduplizierungsabfrage
Verwende das folgende SQL-Muster, um Duplikate zu entfernen und nur die neueste Version jeder Transaktion beizubehalten:-- Deduplicate to latest version of each transaction
SELECT *
FROM (
SELECT *,
ROW_NUMBER() OVER (
PARTITION BY order_item_id
ORDER BY last_update_time_utc DESC
) AS rn
FROM your_transactions_table
) t
WHERE rn = 1;
Upsert-Muster
Verwende dieses Muster, um eine lokale Tabelle mit dem jeweils neuesten Stand jeder Transaktion zu verwalten:MERGE INTO your_table AS target
USING s3_staging_table AS source
ON target.order_item_id = source.order_item_id
WHEN MATCHED AND source.last_update_time_utc > target.last_update_time_utc THEN
UPDATE SET
transaction_datetime_utc = source.transaction_datetime_utc,
net_cogs = source.net_cogs,
net_revenue = source.net_revenue,
last_update_time_utc = source.last_update_time_utc
-- ... all other columns
WHEN NOT MATCHED THEN
INSERT (order_item_id, transaction_datetime_utc, ..., last_update_time_utc)
VALUES (source.order_item_id, source.transaction_datetime_utc, ..., source.last_update_time_utc);
ETL-Pipeline
Übersicht
Befolge diesen vierstufigen Prozess, um eine zuverlässige, automatisierte Ingestion-Pipeline für TVOD-Umsatzdaten aufzubauen.
Pipeline-Schritte
- Erster Datenabruf – Rufe über den API-Endpunkt alle Dateien für deinen Vertrag innerhalb des gewünschten Zeitraums ab. Lade alle zurückgegebenen Dateien herunter. Jede Datei enthält Transaktionsdatensätze im CSV-Format (gzip-komprimiert).
- Deduplizierung – Wenn bei der Verarbeitung von Daten über mehrere Tage mehrere Datensätze mit derselben order_item_id vorhanden sind, behalte mithilfe der Deduplizierungsabfrage in Abschnitt 6.2 nur den Datensatz mit der neuesten last_update_time_utc bei.
- Upsert in das Zielsystem – Führe deduplizierte Datensätze in der Zieltabelle zusammen und verwende dabei order_item_id als Schlüssel. Siehe das Upsert-Muster in Abschnitt 6.3.
- Inkrementelle Verarbeitung – Setze bei fortlaufenden Datenabrufen startDateTime auf den Zeitpunkt des letzten Abrufs und endDateTime auf die aktuelle Uhrzeit. Verarbeite alle zurückgegebenen Dateien und führe ein Upsert in dein Zielsystem durch.
Stell dir die folgenden Parameter für inkrementelle Läufe ein:startDateTime = {last_successful_pull_timestamp}
endDateTime = {current_utc_timestamp}
Empfohlene Abrufhäufigkeit
Empfehlung |
Details |
Empfohlene Häufigkeit |
Alle 4–6 Stunden, um die Daten möglichst aktuell zu halten. |
Strategie für die inkrementelle Verarbeitung |
Setze startDateTime auf den zuletzt abgerufenen Zeitstempel und endDateTime auf die aktuelle Uhrzeit. Verarbeitet alle zurückgegebenen Dateien. |
Tägliche/wöchentliche Datenabrufe |
Wenn du Daten täglich oder wöchentlich abrufst, stelle sicher, dass du alle Dateien für den gesamten Zeitraum verarbeitest, damit keine Datensätze fehlen. |
Empfohlene Startzeit |
Starte tägliche Jobs um 1:00 Uhr UTC, um die Daten des Vortags vollständig zu erfassen. |
Beispielabfragen
Verwende diese SQL-Muster als Ausgangspunkt für gängige Analytics-Anwendungsfälle. Ersetze [START_DATE], [END_DATE] und [X] durch die gewünschten Werte.
Top-X-Titel nach Umsatz in einem bestimmten ZeitraumSELECT
title_name,
COUNT(DISTINCT order_item_id) AS total_orders,
SUM(net_revenue) AS total_revenue
FROM your_table
WHERE transaction_datetime_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY title_name
ORDER BY total_revenue DESC
LIMIT [X];
Gesamtumsatz nach KauftypSELECT
purchase_type,
SUM(net_revenue) AS total_revenue
FROM your_table
WHERE transaction_datetime_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY purchase_type
ORDER BY purchase_type;
Tägliche UmsatzübersichtSELECT
DATE(transaction_datetime_utc) AS transaction_date,
COUNT(DISTINCT order_item_id) AS total_orders,
SUM(net_revenue) AS total_revenue,
SUM(net_cogs) AS total_cogs
FROM your_table
WHERE transaction_datetime_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY DATE(transaction_datetime_utc)
ORDER BY transaction_date DESC;
Umsatz nach GebietSELECT
territory,
COUNT(DISTINCT order_item_id) AS total_orders,
SUM(net_revenue) AS total_revenue
FROM your_table
WHERE transaction_datetime_utc BETWEEN '[START_DATE]' AND '[END_DATE]'
GROUP BY territory
ORDER BY total_revenue DESC;
Qualitätsstandards
Datenqualitätsziele
Qualitätskriterium |
Ziel |
Messung |
Vollständigkeit |
> 99 % der Transaktionen werden erfasst |
Vergleich mit Finanzberichten |
Aktualität |
~9 Stunden End-to-End-Latenz |
Zeit von der Transaktion bis zur Datenverfügbarkeit |
Konsistenz |
Einheitliches standardisiertes Format |
Alle Gebiete in einem Datensatz |
Bekannte Einschränkungen
Einschränkung |
Beschreibung |
Auswirkung |
Verzögerung bei der Kostenerfassung |
net_cogs wird täglich aktualisiert, nicht in Echtzeit. |
Datensätze können anfänglich NULL oder Kosten von 0 anzeigen; die Aktualisierung erfolgt innerhalb von 24 Stunden. |
Datenaufbewahrung |
Maximal 2 Jahre an historischen Daten. |
Anfragen mit Zeitstempeln, die älter als 2 Jahre sind, liefern keine Ergebnisse. |
Token-Ablauf |
LWA-Zugriffstoken laufen nach 1 Stunde ab. |
Für einen unterbrechungsfreien Zugriff muss eine Refresh-Token-Logik implementiert werden. |
Dateibasierte Bereitstellung |
Die API gibt Links zu Dateien zurück, keine direkten Datenzeilen. |
Erfordert vor der Verarbeitung einen Download-Schritt in deiner Pipeline. |
Finanzielle Abweichung |
Geringfügige Abweichungen gegenüber Finanz-/Tantiemenberichten. |
Erwartetes Verhalten aufgrund von Unterschieden bei Datums- und Zeitangaben; kein Problem mit der Datenqualität. |
