#Loyalty events
POST /loyalty-events
Report something your own systems saw to the loyalty engine. The token names a rule whose trigger is set to an event, and the rule decides what the customer earns. Several rules can share a token. The event is queued rather than applied inline, so a 202 means it was accepted, not that anything was awarded yet. Sending the same idempotencyKey twice awards nothing a second time. Programs that are paused are reported back rather than queued.
Requires the loyalty:write permission.
Body Parameters
dataobjectrequiredThe event to report.
Request
curl \
-X POST \
"https://api.cascade.dev/loyalty-events" \
-H "Authorization: Bearer sk_YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"data": {
"token": "string",
"customerEmail": "[email protected]",
"value": 0,
"idempotencyKey": "string",
"createCustomer": true,
"occurredAt": "2025-01-15T09:30:00Z"
}
}'Request
import { client } from "@cascade-commerce/api/admin/client"
import { postLoyaltyEvents } from "@cascade-commerce/api/admin"
client.setConfig({
baseUrl: "https://api.cascade.dev",
headers: { Authorization: "Bearer sk_YOUR_SECRET_KEY" },
})
const { data, error } = await postLoyaltyEvents({
body: {
data: {
token: "string",
customerEmail: "[email protected]",
value: 0,
idempotencyKey: "string",
createCustomer: true,
occurredAt: "2025-01-15T09:30:00Z",
},
},
})Request
require "net/http"
uri = URI("https://api.cascade.dev/loyalty-events")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer sk_YOUR_SECRET_KEY"
req["Content-Type"] = "application/json"
req.body = <<~JSON
{
"data": {
"token": "string",
"customerEmail": "[email protected]",
"value": 0,
"idempotencyKey": "string",
"createCustomer": true,
"occurredAt": "2025-01-15T09:30:00Z"
}
}
JSON
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
puts res.bodyRequest
import json
from urllib.request import Request, urlopen
body = """{
"data": {
"token": "string",
"customerEmail": "[email protected]",
"value": 0,
"idempotencyKey": "string",
"createCustomer": true,
"occurredAt": "2025-01-15T09:30:00Z"
}
}"""
req = Request(
"https://api.cascade.dev/loyalty-events",
data=body.encode(),
headers={
"Authorization": "Bearer sk_YOUR_SECRET_KEY",
"Content-Type": "application/json",
},
)
with urlopen(req) as res:
print(json.load(res))Response
{
"accepted": true,
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"dedupeKey": "string",
"loyaltyProgramIds": ["550e8400-e29b-41d4-a716-446655440000"],
"pausedLoyaltyProgramIds": ["550e8400-e29b-41d4-a716-446655440000"]
}Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"description": "The event reached at least one program. Whether it earns anything is up to that program's rules."
},
"customerId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
"description": "The customer the event was recorded against."
},
"dedupeKey": {
"type": "string",
"description": "The key this event was filed under. Replaying the same idempotency key produces the same one."
},
"loyaltyProgramIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "The programs the event was queued for, resolved from the rules the token names."
},
"pausedLoyaltyProgramIds": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
},
"description": "Programs the token reaches that are paused. A paused program earns nothing, so the event was not queued for it."
}
},
"required": [
"accepted",
"customerId",
"dedupeKey",
"loyaltyProgramIds",
"pausedLoyaltyProgramIds"
],
"additionalProperties": false
}