API-Changelog

Benachrichtigungen über Produkt-Updates - Oktober 2026

Benachrichtigen Sie die Käufer eines Produkts per E-Mail, dass es aktualisiert wurde — die Kampagne, die ein Händler mit „Kunden benachrichtigen“ auf einer Produktseite startet — aus Ihrem eigenen System. Additiv zum v1-Vertrag. In jedem kostenpflichtigen Plan verfügbar.

• Neuer Endpunkt POST /products/{shopify_product_id}/notifications: reiht eine Kampagne (202) für jeden Käufer der herunterladbaren Zuordnungen des Produkts ein, oder, mit variant_ids, der Zuordnungen, die diese Varianten bedienen. Optionale Text-message von bis zu 2.000 Zeichen mit {customer.first_name}, {shop.name}, {product.title} und {product.metafields.<namespace>.<key>}; keine Links. dry_run führt jede Prüfung aus und gibt Zahlen, Betreff und gerenderte Notiz zurück, ohne zu senden (200; verwenden Sie pro Probelauf einen neuen Idempotency-Key). Kostet 10 Rate-Limit-Token.
• Neuer Endpunkt GET /notifications/{notificationId}: Status der Kampagne, Zahlen, waiting_for_archive und ein geschlossenes error-Vokabular; completed mit partial: true, wenn einige Sendungen fehlgeschlagen sind. In der App gestartete Kampagnen erscheinen ebenfalls.
• Neuer Endpunkt POST /notifications/{notificationId}/cancel: bricht eine wartende Kampagne ab (200). Das 7-Tage-Limit des Produkts bleibt bestehen, genau wie beim Abbruch in der App.
• Neues optionales Objekt notify_customers bei POST /mappings und PUT /mappings/{id}: reiht nach dem Commit des Schreibvorgangs eine Benachrichtigung für die Käufer der geschriebenen Zuordnung ein. Eine Notiz, die eine Regel zu ihrem eigenen Text verletzt (leer, zu lang, eine fehlerhafte Variable, mehr als fünf Metafelder, ein Link im Text), ist 422 invalid_message, ohne dass etwas geschrieben wird; ein Metafeld-Problem und jede andere Ablehnung werden im neuen Feld data.notification gemeldet (created: false, error), niemals als 4xx. data.notification ist nur vorhanden, wenn das Flag gesendet wurde; bestehende Antworten bleiben unverändert.
• Eine Kampagne pro Produkt pro 7 Tage, über alle seine Varianten und jede Quelle, und keine, solange eine noch wartet oder sendet: 429 notification_cooldown mit Retry-After (bis zu sieben Tage) und error.details.next_available_at. Nicht der Token-Bucket — nicht automatisch wiederholen; planen Sie den nächsten Aufruf für next_available_at.
• Höchstens 5 wartende oder sendende Kampagnen pro Shop gleichzeitig, über jedes Produkt und jede Quelle hinweg: Eine sechste ist 429 too_many_active_notifications mit error.details.limit und error.details.active_notification_ids und ohne Retry-After. Versuchen Sie es erneut, sobald eine davon abgeschlossen ist. Ein Probelauf wird auf dieselbe Weise abgewiesen; beim Schreiben einer Zuordnung wird dies in data.notification gemeldet.
• Eine Produkt-Update-E-Mail pro Käufer pro Shop pro 24 Stunden, über jede Kampagne hinweg: Ein Käufer, der bereits eine erhalten hat, wird beim Senden der Kampagne übersprungen. Übersprungene Käufer sind weder in sent_count noch in failed_count oder suppressed_count enthalten. Eine Kampagne, die jeden Käufer übersprungen hat, endet als failed mit error: recipients_recently_notified und verbraucht die 7 Tage des Produkts nicht.
• Vor jedem Block von bis zu 500 E-Mails prüft die Kampagne den Shop erneut und stoppt, wenn das Abonnement oder der kostenpflichtige Plan ausgelaufen ist, Kunden-E-Mails deaktiviert wurden, der Versand ausgesetzt wurde oder Alva die Benachrichtigungen abgeschaltet hat. Stoppt sie, bevor jemand eine E-Mail erhalten hat, ist sie failed (plan_required, email_disabled, notifications_suspended oder notifications_switched_off) und gibt die 7 Tage frei; stoppt sie später, ist sie completed mit partial: true. Eine Kampagne, deren Sendungen alle fehlgeschlagen sind, ist failed mit nothing_sent und gibt die 7 Tage ebenfalls frei, und eine, bei der zum Zeitpunkt des Versands niemand mehr übrig war, dem eine E-Mail gesendet werden konnte, ist failed mit no_eligible_recipients und gibt sie ebenso frei.
• Eine Kampagne, deren anvisierte Zuordnung gerade ein ZIP neu erstellt, wartet darauf (waiting_for_archive: true; nur eine Zuordnung, die ein ZIP-Archiv liefert, lässt eine Kampagne warten); eine fehlgeschlagene Neuerstellung oder eine, die 60 Minuten lang keinen Fortschritt macht, während sie läuft (6 Stunden, solange sie noch auf den Start oder einen erneuten Versuch wartet), gezählt ab der Neuerstellung, nicht ab dem Anlegen der Kampagne, lässt die Kampagne mit null Sendungen scheitern und gibt das Limit frei.
• Acht neue Fehlercodes: 403 notifications_suspended, 404 notification_not_found, 409 notification_not_cancellable, 422 invalid_message, 422 no_downloadable_content, 422 no_eligible_recipients, 429 notification_cooldown, 429 too_many_active_notifications. mapping_not_found und multiple_mappings_match erhalten an diesem Endpunkt error.details.unresolved_variant_ids / ambiguous_variant_ids.

Zugriffs-Update - September 2026

Der API-Zugriff ist nicht mehr an eine Freigabe gebunden.

• Jeder kostenpflichtige Plan (Basic, Pro und Enterprise) kann die API nutzen. Erstellen Sie Schlüssel in der App unter Einstellungen → API keys; Sie müssen nichts beantragen.
• Im Free-Plan ist der Tab „API keys“ ausgeblendet, und bestehende Schlüssel geben 402 plan_required zurück, bis der Shop auf einen kostenpflichtigen Plan wechselt.

v1-Update - Juli 2026

Additive Ergänzungen von Fehlercodes und Antwortfeldern zum bestehenden v1-Vertrag.

• Neuer Fehler 422 withdrawal_consent_required am Download-URLs-Endpunkt für Bestellungen: Er wird zurückgegeben, wenn der Shop die EU-Widerrufseinwilligung aktiviert hat und für die Bestellung noch keine Einwilligung erfasst ist; Download-URLs werden ausgestellt, sobald der Kunde einwilligt.
• Neuer Fehler 422 key_limit_reached beim Erstellen von API-Schlüsseln: Ein Shop kann höchstens 25 aktive API-Schlüssel halten; widerrufen Sie zuerst einen.
• Neuer Fehler 409 delivery_not_yet_released an den Endpunkten download-urls und resend für Bestellungen: Er wird zurückgegeben, wenn für das Produkt eine Verzögerung der Download-Zustellung konfiguriert ist und die Dateien des Käufers noch nicht freigeschaltet sind. Bis die Verzögerung abgelaufen ist, werden keine Download-URLs ausgestellt und keine E-Mail versendet.
• Neues Objekt error.details im Fehlerumschlag: Es ist nur bei Codes vorhanden, die für den Aufrufer unbedenklichen Kontext mitliefern. Derzeit ist delivery_not_yet_released der einzige Erzeuger; er enthält release_at, den ISO-8601-Zeitpunkt, zu dem die Downloads freigeschaltet werden. Behandeln Sie das Objekt als offen - neue Schlüssel können ohne Wechsel der Hauptversion hinzukommen.
• Neue Felder delivery_pending und release_at im Kaufobjekt des Bestellstatus: delivery_pending ist true, solange ein Kauf noch durch eine Verzögerung der Download-Zustellung zurückgehalten wird, und release_at ist der ISO-8601-Zeitpunkt der Freischaltung bzw. null, wenn nichts aussteht.
• Der Endpunkt grant-downloads gibt zurückgehaltene Käufe einer Bestellung jetzt sofort frei, sodass Händler eine Verzögerung der Download-Zustellung über die API übersteuern können.

v1.0.0 - Juni 2026

Erste Pilot-API-Oberfläche mit zugangsbeschränktem Zugriff (nur nach Freigabe).

• API-Schlüssel für freigegebene Shops.
• Erforderliche Idempotenz-Schlüssel bei Schreibanfragen.
• Asset-Import per Remote-URL, Direkt-Uploads, Asset-Auflistung, Asset-Aktualisierungen und Asset-Löschung.
• Flache Kategorien, Produktzuordnungen, Pakete und Lizenzschlüssel-Tags.
• Bestellzuweisungen, die zugeordnete Downloads in Shopify-Kundenkonten sichtbar machen.
• Zugriffssteuerung für Bestellungen: Widerruf, Wiederherstellung, Download-Freigabe und erneuter E-Mail-Versand.
• Endpunkte für Job- und Bestellstatus.
• Downloads der OpenAPI-Spezifikation und der Postman-Collection.

Versionierungsrichtlinie

Der v1-Vertrag ist rein additiv: Neue Endpunkte, optionale Felder und neue Fehlercodes können hinzugefügt werden. Breaking Changes werden einen künftigen /api/v2-Pfad verwenden.