Handbuch zur Prämiendefinition reward-definition-guide

Auf dieser Seite Sie, wie Sie Belohnungsanbieter und Belohnungsdefinitionen konfigurieren, JSONata-Ausdrücke für Belohnungen schreiben und den Kontext verstehen, der zum Generieren von Payloads für die Erfüllung verwendet wird.

Wenn eine Challenge-Aufgabe, ein Meilenstein oder eine Challenge abgeschlossen und ein Belohnungswert konfiguriert wurde gibt die Plattform eine Belohnung aus, indem sie den HTTP-Endpunkt Ihres Belohnungsanbieters mit einer JSON-Payload aufruft. Eine Belohnungsdefinition beschreibt, welche Belohnung ausgegeben werden soll, und bietet einen JSONata-Ausdruck - rewardJsonata - der die genaue Payload formt, die Ihr Anbieter erwartet.

In diesem Handbuch wird beschrieben, wie Sie einen Belohnungsanbieter konfigurieren, Belohnungsdefinitionen erstellen, den rewardJsonata Ausdruck schreiben und verstehen, welcher Kontext zur Auswertungszeit für ihn verfügbar ist.

➡️ Erfahren Sie, wie Sie einen Anbieter von Treueprämien einrichten

Modell mit zwei Ebenen

Die Belohnungen sind in zwei Stufen organisiert:

Reward Provider  (endpoint, auth, headers)
└── Reward Definition  (denomination, rewardJsonata)
└── Reward Definition
└── ...

Ein Belohnungsanbieter stellt ein einzelnes externes Belohnungssystem dar und enthält die URL des Versandendpunkts, die Authentifizierung und alle benutzerdefinierten HTTP-Kopfzeilen. Ein Anbieter kann mehrere Belohnungsdefinitionen besitzen, die jeweils einen anderen Belohnungstyp oder eine andere von diesem Anbieter angebotene Bezeichnung beschreiben (z. B. „50 Sterne“, „Doppelsterne“, „Gratis-Artikel„).

Eine Challenge verweist auf den Anbieter und die Definition per GUID. Wenn eine Belohnung ausgegeben wird, bewertet die Plattform den rewardJsonata Ausdruck der Definition und sendet das Ergebnis an den Endpunkt des Anbieters.

Belohnungsanbieter- und Definitionsfelder

Felder des Belohnungsanbieters
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 5-row-4 6-row-4 7-row-4 8-row-4 html-authored
Feld Typ Erforderlich Beschreibung
guid String Nein (vom System zugewiesen) Eindeutige Kennung. Schreibgeschützt.
name String Ja Anzeigename, innerhalb der Organisation eindeutig.
desc String Nein Lesbare Beschreibung des Anbieters.
enabled Boolean Nein Wenn false, wird der Versand
Belohnungen für alle Definitionen unter diesem Anbieter ausgesetzt.
url String Ja HTTP-Endpunkt, der die Belohnungs-Payload erhält.
Die Plattform sendet die ausgewertete
rewardJsonata an diese URL.
additionalHeaders Object Nein Benutzerdefinierte HTTP-Kopfzeilen, die in jede Versandanfrage
werden sollen (z. B. API-Schlüssel
Inhaltsüberschreibungen).
maxRatePerSecond Integer Nein Optionales Ratenlimit pro Anbieter (1-5000).
Null bedeutet unbegrenzt.
enableMTLS Boolean Nein Ob der Endpunkt gegenseitiges TLS erfordert.
Felder zur Belohnungsdefinition
table 0-row-4 1-row-4 2-row-4 3-row-4 4-row-4 5-row-4 6-row-4 7-row-4 html-authored
Feld Typ Erforderlich Beschreibung
guid String Nein (vom System zugewiesen) Eindeutige Kennung. Schreibgeschützt.
name String Ja Anzeigename, innerhalb des Anbieters eindeutig.
denomination String Nein Die Einheit der Belohnung, die in der Anzeige verwendet wird
in Ausdrücken verfügbar ist als
reward.denomination
(z. B. "Stars", "Points", "Miles").
desc String Nein Beschreibung der Belohnung,
Ausdrücke als reward.desc verfügbar.
enabled Boolean Nein Wenn false, ist diese Definition inaktiv
gibt keine Belohnungen aus.
isDefault Boolean Nein Markiert dies als die Sandbox-weite Standard
Belohnungsdefinition. Es kann immer nur
eine Standarddefinition für alle Anbieter vorhanden sein. Wenn
einen neuen Standard festlegen, wird der vorherige Standard gelöscht.
Wird zum automatischen Ausfüllen von Belohnungsdetails für
Herausforderungen zum Zeitpunkt der Veröffentlichung verwendet.
rewardJsonata String Ja JSONata-Ausdruck, der zum Zeitpunkt
Belohnungsproblems ausgewertet wird Erhält den vollständigen
und muss die JSON-Payload
POST an den Anbieter zurückgeben.

Der Belohnungskontext

Wenn rewardJsonata ausgewertet wird, erhält es ein einzelnes Stammobjekt, das alles über das Belohnungsereignis Bekannte enthält. Alle Pfade in Ihrem Ausdruck sind relativ zu diesem Stamm.

{
  "rewardContext": {
    "rewardValue": "50",
    "source":      "challenge"
  },
  "reward": {
    "name":         "500 Stars",
    "desc":         "Issue 500 Stars to the member",
    "denomination": "Stars",
    "enabled":      true
  },
  "task": { ... },
  "milestone": { ... },
  "challenge": { ... },
  "timestamp": "2026-02-10T00:29:22.538+00:00"
}
Kontextfelder
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2
Feld Beschreibung
rewardContext.rewardValue Die Zeichenfolge des Belohnungswerts, die für die Herausforderung, Aufgabe oder den Meilenstein konfiguriert wurde, die/der diese Ausgabe ausgelöst hat.
rewardContext.source Was die Belohnung ausgelöst hat: "task", "challenge" oder "milestone".
reward Die Belohnungsdefinition selbst — name, desc, denomination.
task Die abgeschlossene Aufgabe, einschließlich ihrer accumulators, schedule und reward.
task.accumulators.spend Gesamtzahl der von der Aufgabe kumulierten qualifizierten Ausgaben.
task.accumulators.qty Gesamtzahl der von der Aufgabe kumulierten qualifizierten Elemente.
task.accumulators.item_list Alle qualifizierten Elemente, die auf die Aufgabe angewendet wurden. Jeder Eintrag hat item, transactionId, timestamp, utcOffset, locationId.
task.accumulators.item_list[-1] Das zuletzt angewendete Element (JSONata-negativer Index). Nützlich für die Suche nach der letzten Transaktions-ID oder dem letzten Zeitstempel.
task.schedule.currentStreak Aktuelle Anzahl aufeinander folgender Besuche (für Streak-Herausforderungen).
task.schedule.currentVisits Besuchsanzahl insgesamt (für Besuchsherausforderungen).
milestone Der Meilenstein, der diese Belohnung ausgelöst hat, oder null, wenn nicht eine Meilensteinbelohnung. Enthält count und reward.rewardValue.
challenge.profileId Die Treue-ID des Mitglieds.
challenge.kvpCustom Benutzerdefinierte Schlüssel-Wert-Paare, die für die Challenge konfiguriert sind. Ein gängiges Muster für die Übergabe von Kampagnen-IDs, Produktnamen oder anbieterspezifischen Metadaten.
challenge.name Name der Herausforderung.
challenge._id Challenge-ID.
timestamp ISO 8601-Zeitstempel der Belohnungsausgabe.

Schreiben des rewardJsonata-Ausdrucks

Der Ausdruck empfängt den Belohnungskontext als Eingabe und muss ein JSON-Objekt zurückgeben - die an den Endpunkt des Anbieters gepostete Payload. Die Form dieses Objekts hängt vollständig von der API des Anbieters ab. Sie ordnen Kontextfelder welcher Struktur auch immer der Anbieter erwartet.

Einfache feste Payload

Der einfachste Fall: Der Provider benötigt eine Punktzahl und eine Mitglieds-ID, die beide aus dem Kontext bekannt sind.

code language-jsonata
{
  "memberId":   challenge.profileId,
  "points":     $number(rewardContext.rewardValue),
  "currency":   reward.denomination
}

Ausgabe:

code language-json
{
  "memberId": "ADB-0000030",
  "points":   50,
  "currency": "Stars"
}

rewardContext.rewardValue ist immer eine Zeichenfolge. Verwenden Sie $number(), um sie zu konvertieren, wenn Ihr Anbieter einen numerischen Wert erwartet.

Verwenden von kvpCustom für anbieterspezifische Metadaten

Anbieter benötigen häufig Felder wie Kampagnen-IDs oder Quellsystem-Codes, die für jede Challenge-Ausführung spezifisch sind. Speichern Sie diese beim Verfassen der Herausforderung in challenge.kvpCustom und referenzieren Sie sie dann im Ausdruck. So bleibt der Ausdruck kampagnenübergreifend wiederverwendbar.

code language-jsonata
{
  "memberId":         challenge.profileId,
  "points":           $number(rewardContext.rewardValue),
  "campaignId":       challenge.kvpCustom.campaignId,
  "transactionSource": "AJO"
}

Sie können auch reward.kvpCustom für Konstanten verwenden, die für einen bestimmten Belohnungstyp und nicht pro Herausforderung festgelegt sind.

Verwenden der Daten des Aufgabenakkumulators

Aufgabenakkumulatoren halten Aufzeichnungen über jedes qualifizierte Ereignis bereit. Verwenden Sie item_list[-1] , um auf das zuletzt angewendete Element zuzugreifen - seine transactionId und timestamp sind für Audit-Trails und Deduplizierung auf Anbieterseite nützlich.

code language-jsonata
{
  "memberId":       challenge.profileId,
  "points":         $number(rewardContext.rewardValue),
  "transactionId":  task.accumulators.item_list[-1].transactionId,
  "transactionDate": task.accumulators.item_list[-1].timestamp
}
Erstellen einer Textnachricht

Bei benachrichtigungsbasierten Anbietern (Slack, Mobile Message, E-Mail) können Sie eine Nachrichtenzeichenfolge direkt mit dem & Verkettungsoperator von JSONata erstellen:

code language-jsonata
{
  "text": "You just earned " & rewardContext.rewardValue & " " & reward.denomination & "!"
}

Ausgabe:

code language-json
{
  "text": "You just earned 50 Stars!"
}

Beispiele

Beispiel 1: Einfacher Punktanbieter

Szenario: grundlegende Treuepunkte-API erwartet eine Mitglieder-ID und einen Punktbetrag.

Belohnungsdefinition:

code language-json
{
  "name":         "Standard Points",
  "denomination": "Points",
  "desc":         "Award loyalty points",
  "enabled":      true,
  "rewardJsonata": "{\"memberId\": challenge.profileId, \"pointQuantity\": $number(rewardContext.rewardValue), \"denomination\": reward.denomination}"
}

Formatierter Ausdruck:

code language-jsonata
{
  "memberId":      challenge.profileId,
  "pointQuantity": $number(rewardContext.rewardValue),
  "denomination":  reward.denomination
}

Payload an Provider gepostet:

code language-json
{
  "memberId":      "ADB-0000030",
  "pointQuantity": 50,
  "denomination":  "Points"
}
Beispiel 2: Provider-Payload mit Kampagnen-Metadaten

Szenario: Anbieter benötigt einen strukturierten Prämiensatz, der Auditfelder, Kampagnenverweise und Mitgliederbeschreibungen enthält. Kampagnenspezifische Werte werden in challenge.kvpCustom gespeichert, sodass dieselbe Belohnungsdefinition über Kampagnen hinweg funktioniert, ohne den Ausdruck zu bearbeiten.

Challenge-kvpCustom (festgelegt bei der Bearbeitung der Challenge):

code language-json
{
  "parentCampaignId": "CAMP-2026-Q1",
  "productName":      "Loyalty Program"
}

Belohnungsdefinition:

code language-json
{
  "name":         "Stars — Campaign Award",
  "denomination": "Stars",
  "desc":         "Issue Stars for completing a qualifying purchase",
  "enabled":      true,
  "rewardJsonata": "{\"awardPoints\":[{\"idType\":\"externalId\",\"id\":challenge.profileId,\"transactionId\":task.accumulators.item_list[-1].transactionId,\"transactionDate\":task.accumulators.item_list[-1].timestamp,\"originalTransactionId\":task.accumulators.item_list[-1].transactionId,\"transactionSource\":\"AJO\",\"channelSource\":\"Web\",\"parentCampaignId\":challenge.kvpCustom.parentCampaignId,\"productName\":challenge.kvpCustom.productName,\"memberAwardDescription\":reward.desc,\"pointQuantity\":$number(rewardContext.rewardValue)}]}"
}

Formatierter Ausdruck:

code language-jsonata
{
  "awardPoints": [
    {
      "idType":                "externalId",
      "id":                    challenge.profileId,
      "transactionId":         task.accumulators.item_list[-1].transactionId,
      "transactionDate":       task.accumulators.item_list[-1].timestamp,
      "originalTransactionId": task.accumulators.item_list[-1].transactionId,
      "transactionSource":     "AJO",
      "channelSource":         "Web",
      "parentCampaignId":      challenge.kvpCustom.parentCampaignId,
      "productName":           challenge.kvpCustom.productName,
      "memberAwardDescription": reward.desc,
      "pointQuantity":         $number(rewardContext.rewardValue)
    }
  ]
}

Payload an Provider gepostet:

code language-json
{
  "awardPoints": [
    {
      "idType":                "externalId",
      "id":                    "ADB-0000030",
      "transactionId":         "b4fa0e89-f4bb-41ce-b370-fb97f9c52f1a",
      "transactionDate":       "2026-02-08T00:12:00.000+00:00",
      "originalTransactionId": "b4fa0e89-f4bb-41ce-b370-fb97f9c52f1a",
      "transactionSource":     "AJO",
      "channelSource":         "Web",
      "parentCampaignId":      "CAMP-2026-Q1",
      "productName":           "Loyalty Program",
      "memberAwardDescription": "Issue Stars for completing a qualifying purchase",
      "pointQuantity":         50
    }
  ]
}
Beispiel 3 — Meilenstein-Belohnung

Szenario: Streak Challenge gibt alle N Besuche eine Meilensteinbelohnung aus. Der Ausdruck enthält die Meilensteinanzahl und den aktuellen Stream für den anbieterseitigen Kontext.

Formatierter Ausdruck:

code language-jsonata
{
  "memberId":       challenge.profileId,
  "points":         $number(rewardContext.rewardValue),
  "milestoneCount": milestone.count,
  "currentStreak":  task.schedule.currentStreak,
  "denomination":   reward.denomination,
  "source":         rewardContext.source
}

Payload an Provider gepostet (beim zweiten Meilenstein des Besuchs):

code language-json
{
  "memberId":       "ADB-0000030",
  "points":         20,
  "milestoneCount": 2,
  "currentStreak":  2,
  "denomination":   "Stars",
  "source":         "milestone"
}

Wenn rewardContext.source "milestone" wird, wird das milestone mit count und reward.rewardValue befüllt. Wenn die Quelle "task" oder "challenge" ist, wird milestone null.

API-Referenz

Prämienanbieter
code language-http
POST   /loyalty/metadata/config/rewards/providers
GET    /loyalty/metadata/config/rewards/providers
GET    /loyalty/metadata/config/rewards/providers/{providerId}
PUT    /loyalty/metadata/config/rewards/providers/{providerId}
DELETE /loyalty/metadata/config/rewards/providers/{providerId}

Für alle Anfragen sind x-gw-ims-org-id und x-sandbox-name Kopfzeilen erforderlich.

Anbieter erstellen:

code language-http
POST /loyalty/metadata/config/rewards/providers
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}
Content-Type: application/json

{
  "name":    "My Points Provider",
  "desc":    "Issues loyalty points via REST",
  "enabled": true,
  "url":     "https://rewards.example.com/award",
  "additionalHeaders": {
    "x-api-key": "YOUR_API_KEY"
  }
}
Prämiendefinitionen
code language-http
POST   /loyalty/metadata/config/rewards/definitions/{providerId}
GET    /loyalty/metadata/config/rewards/definitions/{providerId}
GET    /loyalty/metadata/config/rewards/definitions/{providerId}/{rewardId}
PUT    /loyalty/metadata/config/rewards/definitions/{providerId}/{rewardId}
DELETE /loyalty/metadata/config/rewards/definitions/{providerId}/{rewardId}

Erstellen Sie eine Belohnungsdefinition:

code language-http
POST /loyalty/metadata/config/rewards/definitions/{providerId}
x-gw-ims-org-id: {ORG_ID}
x-sandbox-name: {SANDBOX}
Content-Type: application/json

{
  "name":         "50 Stars",
  "denomination": "Stars",
  "desc":         "Award 50 Stars on task completion",
  "enabled":      true,
  "rewardJsonata": "{ \"memberId\": challenge.profileId, \"points\": $number(rewardContext.rewardValue) }"
}

Validierung von Ausdrücken

rewardJsonata Ausdrücke werden zum Zeitpunkt der Veröffentlichung auf Syntax überprüft. Wenn der Ausdruck ungültig ist, gibt die API einen 422 mit einer Beschreibung des Analysefehlers zurück.

Um einen Ausdruck vor der Veröffentlichung zu entwickeln und zu testen, verwenden Sie den JSONata Exerciser. Fügen Sie das Belohnungskontext-JSON als Eingabedokument und Ihren Ausdruck ein, um zu überprüfen, ob die Ausgabe mit den Erwartungen Ihres Anbieters übereinstimmt. Ein repräsentativer Belohnungskontext für jeden Trigger (task, milestone, challenge) wird in den obigen Beispielen gezeigt.

Häufige Fehler

Fehler
Ergebnis
Korrigieren
rewardContext.rewardValue als Zahl ohne Konversion verwendet
Nicht übereinstimmender Typ, wenn der Anbieter das Feld als numerisch validiert
Mit $number(rewardContext.rewardValue) umschließen
challenge.kvpCustom.someKey gibt null zurück
Schlüssel wurde bei der Bearbeitung der Anfrage nicht festgelegt
Stellen Sie sicher, dass der Schlüssel bei jeder Herausforderung, die diese Definition verwendet, in kvpCustom vorhanden ist
task.accumulators.item_list[-1] ist null
Vor der Vergabe der Belohnung wurden keine Elemente angewendet (Nicht-Kaufereignis)
Schützen Sie stattdessen mit einem bedingten oder verwenden Sie timestamp aus dem Kontext .
milestone Zugriff, wenn die Quelle "task" oder "challenge" ist
milestone ist null; Ausdruck löst NULL-Felder aus oder erzeugt sie
rewardContext.source vor dem Zugriff auf milestone prüfen oder milestone nur in Definitionen verwenden, die an Meilenstein-Prämien angehängt sind
Ausdruck gibt ein Array anstelle eines Objekts zurück
Anbieter erhält unerwartete Payload-Struktur
Wrap array-returned-Ausdrücke in einem äußeren Objekt: { "items": [...] }

Anleitungsvideos video

➡️ Erfahren Sie, wie Sie einen Anbieter von Treueprämien einrichten

AI Knowledge Reference

This section contains structured knowledge intended to support interpretation, retrieval, and question answering related to this topic.

For complete understanding, this information should be combined with the documentation on this page. Neither source is intended to stand alone; the page describes the feature, while this section provides additional context that helps disambiguate terminology, intent, applicability, and constraints.

  • TL;DR: This page explains how to configure reward providers and reward definitions for Loyalty Challenges, including the fields involved, the reward context passed to the rewardJsonata expression, and how to write that expression to build the payload posted to a reward provider’s endpoint.

Intents:

  • Configure a reward provider (endpoint, authentication, headers) and one or more reward definitions under it.
  • Understand the fields available on reward providers and reward definitions, including which are required.
  • Write a rewardJsonata expression that maps reward context fields onto the payload a provider expects.
  • Use kvpCustom on a challenge to pass campaign-specific or provider-specific metadata without editing the expression.
  • Use task accumulator data, such as the most recent item in item_list, inside an expression.
  • Distinguish task, milestone, and challenge reward sources and access the milestone object correctly.
  • Validate a rewardJsonata expression before publishing and troubleshoot common mistakes.

Glossary:

  • Reward Provider (product-specific): represents a single external rewards system; holds the delivery endpoint URL, authentication, and custom HTTP headers.
  • Reward Definition (product-specific): describes a distinct reward type or denomination offered by a provider, including its rewardJsonata expression.
  • rewardJsonata (product-specific): a JSONata expression configured on a reward definition that is evaluated at reward-issue time and must return the JSON payload to POST to the provider.
  • Reward context (product-specific): the single root object passed to rewardJsonata at evaluation time, containing rewardContext, reward, task, milestone, challenge, and timestamp.
  • kvpCustom (product-specific): custom key-value pairs configured on a challenge (challenge.kvpCustom) or available as constants on a reward (reward.kvpCustom), used to pass campaign IDs, product names, or provider-specific metadata.
  • isDefault (product-specific): marks a reward definition as the sandbox-wide default, used to auto-populate reward details on personalized challenges at publish time.
  • item_list (product-specific): the list of all qualifying items applied to a task’s accumulators; item_list[-1] accesses the most recently applied item via JSONata negative indexing.

Guardrails:

  • name and url are required fields on a reward provider; guid is system-assigned and read-only.
  • name and rewardJsonata are required fields on a reward definition; guid is system-assigned and read-only.
  • When a reward provider’s enabled field is false, reward delivery is suspended for all definitions under that provider.
  • When a reward definition’s enabled field is false, that definition is inactive and will not issue rewards.
  • Only one reward definition across all providers may be marked as default (isDefault) at a time; setting a new default clears the previous one.
  • maxRatePerSecond on a reward provider accepts a value from 1 to 5000 (per provider); null means unlimited.
  • rewardContext.rewardValue is always a string; it must be converted with $number() if the provider expects a numeric value.
  • milestone is null when the reward source is "task" or "challenge"; it is populated (with count and reward.rewardValue) only when rewardContext.source is "milestone".
  • rewardJsonata expressions are validated for syntax at publish time; an invalid expression causes the API to return a 422 error with a description of the parse failure.
  • challenge.kvpCustom.someKey returns null if the key was not set on the challenge at authoring time.
  • task.accumulators.item_list[-1] is null if no items were applied before the reward was issued (a non-purchase event).
  • If a rewardJsonata expression returns an array instead of an object, the provider receives an unexpected payload structure; it must be wrapped in an outer object.

Terminology:

  • Canonical name: Reward Provider — holds the endpoint, authentication, and headers for an external rewards system.
  • Canonical name: Reward Definition — describes a reward type or denomination and its rewardJsonata expression; belongs to one Reward Provider.
  • Do not confuse: “Reward Provider” (the external system’s endpoint, auth, and headers) ≠ “Reward Definition” (a specific reward type/denomination with its own rewardJsonata, nested under a provider).
  • Do not confuse: “challenge.kvpCustom” (per-challenge custom metadata) ≠ “reward.kvpCustom” (constants fixed for a given reward type).
  • Do not confuse: rewardContext.rewardValue (the reward value string that triggered issuance) ≠ milestone.reward.rewardValue (the reward value specific to a milestone).

FAQ:

  • Q: What triggers a reward to be issued? — When a challenge task, milestone, or challenge completes and has a reward value configured, the platform issues a reward by calling the reward provider’s HTTP endpoint with a JSON payload.
  • Q: What fields are required to create a reward provider? — name and url are required; guid is system-assigned and read-only.
  • Q: What fields are required to create a reward definition? — name and rewardJsonata are required; guid is system-assigned and read-only.
  • Q: How many reward definitions can be marked as default? — Only one definition across all providers may be default at a time; setting a new default clears the previous one.
  • Q: Why does rewardContext.rewardValue need conversion before use as a number? — Because rewardContext.rewardValue is always a string; use $number() to convert it if the provider expects a numeric value.
  • Q: Why would challenge.kvpCustom.someKey return null? — Because the key was not set on the challenge at authoring time; ensure the key is present in kvpCustom on every challenge that uses the definition.
  • Q: What happens if an invalid rewardJsonata expression is published? — The API returns a 422 error with a description of the parse failure.
  • Q: Where can I test a rewardJsonata expression before publishing? — In the JSONata Exerciser, by pasting the reward context JSON as the input document and the expression to verify the output.

Troubleshooting:

  • task.accumulators.item_list[-1] is null — Cause: no items were applied before the reward was issued (a non-purchase event). Fix: guard with a conditional or use timestamp from context instead.
  • milestone accessed when source is "task" or "challenge" — Cause: milestone is null in that case. Fix: check rewardContext.source before accessing milestone, or only use milestone in definitions attached to milestone rewards.
  • Expression returns an array instead of an object — Cause: the provider receives an unexpected payload structure. Fix: wrap array-returning expressions in an outer object, for example { "items": [...] }.
  • challenge.kvpCustom.someKey returns null — Cause: the key was not set on the challenge at authoring time. Fix: ensure the key is present in kvpCustom on every challenge that uses this definition.
  • 422 error — Cause: the rewardJsonata expression is invalid at publish time. Fix: the API returns a description of the parse failure; use the JSONata Exerciser to develop and test the expression before publishing.

Examples:

  • Simple fixed payload: maps challenge.profileId, $number(rewardContext.rewardValue), and reward.denomination into a memberId/points/currency object, producing {"memberId": "ADB-0000030", "points": 50, "currency": "Stars"}.
  • Using kvpCustom: an expression references challenge.kvpCustom.campaignId alongside challenge.profileId and rewardContext.rewardValue to keep the expression reusable across campaigns.
  • Using task accumulator data: an expression uses task.accumulators.item_list[-1].transactionId and .timestamp for audit trails and deduplication on the provider side.
  • Constructing a text message: an expression concatenates strings with &, for example "You just earned " & rewardContext.rewardValue & " " & reward.denomination & "!", producing {"text": "You just earned 50 Stars!"}.
  • Example 1 — Simple points provider: a Reward Definition with rewardJsonata mapping challenge.profileId, $number(rewardContext.rewardValue), and reward.denomination to memberId, pointQuantity, and denomination, producing a payload with pointQuantity: 50.
  • Example 2 — Provider payload with campaign metadata: a Reward Definition builds an awardPoints array using challenge.kvpCustom.parentCampaignId and challenge.kvpCustom.productName (set on the challenge) plus task accumulator transaction data, so the same definition works across campaigns without editing the expression.
  • Example 3 — Milestone reward: an expression includes milestone.count and task.schedule.currentStreak; when rewardContext.source is "milestone", the milestone object is populated with count and reward.rewardValue.

Personas:

  • admin: Can configure a reward provider with its endpoint URL, authentication, and additional headers, and create reward definitions under it. Can set maxRatePerSecond between 1 and 5000, or leave it null for unlimited. Can mark enabled to false on a provider or definition to suspend or stop reward delivery. The page states that only one reward definition across all providers may be isDefault at a time. Where: “Reward provider & definition fields”.

Onboarding:

  • Level: Intermediate
  • First minimal step: Paste the reward context JSON as the input document in the JSONata Exerciser and add your rewardJsonata expression.
  • Success check: The output matches what your provider expects.
recommendation-more-help
journey-optimizer-help