Dieser Endpunkt führt eine eigene Sammelaktion für einen Kunden aus. Punkte, Wiederholungsgrenzen und Höchstwert pro Kunde entsprechen den Einstellungen, die Sie im Dashboard für die Aktion festgelegt haben. Die API löst lediglich die Ausführung aus.

Verwenden Sie diese Möglichkeit, wenn ein System außerhalb von JeriCommerce – etwa Ihr CRM, eine Bewertungsplattform oder ein Umfragetool – festlegt, ob ein Kunde die Punkte erhält.

Die vollständige maschinenlesbare Spezifikation mit interaktivem Test finden Sie beim Endpunkt Execute Custom Earning Flow in der JeriCommerce-API-Dokumentation.

Endpunkt 

// POST
https://api.jericommerce.com/v1/programs/{programId}/custom-earning-flows/{earningFlowId}/execute

Ersetzen Sie {programId} durch die tatsächliche Programm-ID (zu finden unter Settings → Technical → Program Information) und {earningFlowId} durch einen der folgenden Werte:

  • Die Kennung des Platzes für die Sammelaktion: CUSTOM_1, CUSTOM_2, CUSTOM_3, CUSTOM_4 oder CUSTOM_5.
  • Die UUID der entsprechenden Zeile ProgramEngagementFlow, wenn Sie lieber stabile IDs verwenden.

Die Platzkennung ist einfacher, da sie unverändert bleibt, auch wenn Sie die Sammelaktion zurücksetzen.

Authentifizierung

Dieser Endpunkt akzeptiert zwei Authentifizierungsmethoden. Wählen Sie die passende für Ihren Anwendungsfall.

Verwenden Sie den API-Schlüssel Ihres Programms im Header `api-key`. Siehe [Authentifizierung über die API](/integrations/api/1-authentication-through-the-api/).

Mit einem API-Schlüssel können Sie die Aktion für **jeden** Kunden Ihres Programms ausführen. Die E-Mail-Adresse des Kunden ist im Anfrage-Body erforderlich.

Übermitteln Sie das JWT des Kunden im Header `Authorization`. Die Aktion wird für den authentifizierten Kunden ausgeführt und der Anfrage-Body bleibt leer.

Verwenden Sie diese Methode, wenn der Browser oder die App des Kunden selbst den Endpunkt aufruft, zum Beispiel bei einer eigenen Shop-Integration.

Anfrage-Body 

{
  "customerEmail": "customer@example.com"
}
Feld Typ Erforderlich Hinweise
customerEmail string Bei API-Schlüssel-Authentifizierung erforderlich. Bei Customer-JWT-Authentifizierung ignoriert. E-Mail-Adresse des Kunden, der Punkte erhalten soll. Der Kunde muss bereits im Programm angemeldet sein.

Antwort

Bei erfolgreicher Anfrage wird 200 mit einem JSON-Body zurückgegeben:

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}
Feld Typ Hinweise
pointsAwarded number Anzahl der Punkte, die bei dieser Ausführung dem Punktestand des Kunden gutgeschrieben wurden.
remainingExecutions number Anzahl der weiteren Ausführungen innerhalb des aktuellen Wiederholungszeitraums. 0 bedeutet, dass das Limit erreicht wurde.
recurrence string Wiederholungszeitraum der Aktion: once, daily, weekly, monthly, quarterly, semiannually oder yearly.

Fehler

Kann die Anfrage nicht abgeschlossen werden, gibt die API einen Fehlercode zurück, damit Ihre Integration reagieren kann.

Code Bedeutung
CUSTOMER_EMAIL_REQUIRED Sie verwenden API-Schlüssel-Authentifizierung, haben aber customerEmail im Body nicht mitgesendet.
EARNING_FLOW_NOT_FOUND earningFlowId ist in diesem Programm nicht vorhanden.
NOT_A_CUSTOM_EARNING_FLOW Die Flow-ID verweist auf eine Standardaktion (z. B. INCENTIVIZE_PURCHASES), die auf diesem Weg nicht ausgelöst werden kann.
EARNING_FLOW_INACTIVE Die Sammelaktion existiert, ist aber im Dashboard deaktiviert.
EARNING_FLOW_NOT_CONFIGURED Erforderliche Eigenschaften der Sammelaktion fehlen (Punkte, Wiederholung oder maximale Ausführungen). Öffnen und speichern Sie die Aktion im Dashboard.
CUSTOMER_NOT_FOUND Im Programm gibt es keinen Kunden mit dieser E-Mail-Adresse.
MAX_EXECUTIONS_REACHED Der Kunde hat die Sammelaktion im aktuellen Wiederholungszeitraum bereits so oft wie zulässig ausgeführt.

Beispiel

Sie richten CUSTOM_2 so ein, dass Kunden für das Ausfüllen einer Umfrage nach dem Kauf 100 Punkte, einmal während der Mitgliedschaft, erhalten. Das Umfragetool ruft den Endpunkt auf, wenn ein Kunde seine Antwort absendet.

// Request

POST https://api.jericommerce.com/v1/programs/{{program_id}}/custom-earning-flows/CUSTOM_2/execute
api-key: {your_api_key}
Content-Type: application/json

{
  "customerEmail": "customer@example.com"
}

// Response

{
  "pointsAwarded": 100,
  "remainingExecutions": 0,
  "recurrence": "lifetime"
}

Der Punktestand des Kunden steigt um 100 Punkte, und die Sammelaktionskarte in der Web-App zeigt anschließend „You already earned this“ an.

Wenn Sie die Aktion über Shopify Flow oder Klaviyo auslösen, müssen Sie die Anfrage nicht selbst erstellen. Verwenden Sie die Aktion Execute earning flow, die unter Shopify Flows und Ereignisse beschrieben ist, oder erstellen Sie mit dem Klaviyo Webhook Builder einen Webhook zum direkten Einfügen.