reward_granted

POST

Sent once for each coupon given out. coupon.ref and coupon.name are your own reference and name for the coupon, from when you added it, so you can match it in your own system. They are null for a coupon added without them. The code itself is sent, as coupon.code, only to an endpoint with includeCouponCodes turned on.

source says how the coupon was given, and decides which fields are present:

• rule: the player met a prize’s rule at the end of a play. Carries grantId, participantRef, sessionId and expiresAt.
• draw: the player won a draw. Carries grantId, participantRef, expiresAt, runId and winnerId.
• manual: given by hand through the API or dashboard. Carries grantId, participantRef and expiresAt.

Signed and retried as described under session_completed.

Authorizations

• apiKey

Parameters

Header Parameters

X-Keliplay-Signature

required

string

t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the endpoint secret.

Example

t=1760277802,v1=5f2b7c0e9a1d4b3c8e6f0a2d4c6b8e0f1a3c5e7092b4d6f8a0c2e4b6d8f0a1c3

X-Keliplay-Event

required

string

Allowed values: session_completed winner_selected reward_granted

The event type, the same as type in the body.

X-Keliplay-Delivery-Id

required

string

Unique per delivery, and the same on every retry of it.

Request Body^required

Media typeapplication/json

object

type

required

string

Allowed values: session_completed winner_selected reward_granted

createdAt

required

string format: date-time

data

required

object

type

required

Allowed value: reward_granted

data

required

object

gameInstanceId

required

string

channelId

required

The channel the campaign runs on.

string

tierId

required

The prize this coupon was for.

string

prize

required

object

title

required

string

description

string

coupon

required

Your own reference and name for the coupon, from when you added it. code is present only for an endpoint with includeCouponCodes turned on.

object

ref

required

string | null

name

required

string | null

code

The coupon code. Only for endpoints that opted in.

string

source

required

How the coupon was given.

• rule: the player met a prize’s rule at the end of a play.
• draw: the player won a draw.
• manual: given by hand.

string

Allowed values: rule draw manual

grantId

required

The grant. Look it up in GET .../reward-grants.

string

participantRef

required

string

sessionId

Present for rule.

string

expiresAt

required

When the coupon stops being valid. Null means no expiry.

string | null format: date-time

runId

Present for draw.

string

winnerId

Present for draw.

string

Example

{
  "type": "reward_granted",
  "createdAt": "2026-10-12T14:03:22.000Z",
  "data": {
    "gameInstanceId": "0192f3a1-0000-7000-8000-0000000ca001",
    "channelId": "0192f3a1-0000-7000-8000-0000000cb001",
    "grantId": "0192f3a1-0000-7000-8000-000000073001",
    "participantRef": "user_48213",
    "source": "rule",
    "sessionId": "0192f3a1-0000-7000-8000-000000050001",
    "tierId": "0192f3a1-0000-7000-8000-000000071001",
    "prize": {
      "title": "Free coffee"
    },
    "coupon": {
      "ref": "CRM-00417",
      "name": "Free coffee"
    },
    "expiresAt": "2026-11-11T14:03:22.000Z"
  }
}

Responses

200

Any 2xx tells Keliplay the delivery arrived.