Grant a coupon

POST

/v1/game-instances/{campaignId}/reward-grants

const url = 'https://api.keliplay.com/v1/game-instances/example/reward-grants';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"participantRef":"user_48213","idempotencyKey":"goodwill-ticket-5521"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.keliplay.com/v1/game-instances/example/reward-grants \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "participantRef": "user_48213", "idempotencyKey": "goodwill-ticket-5521" }'

Gives a coupon to a named player by hand, outside any rule or draw. The response carries the full code. A reward_granted webhook is sent with source: manual.

idempotencyKey makes retries safe. If no code is available, or the player already has one and the reward gives one per player, the response is 409.

Permission: rewards.grant. Plan feature: Rewards. Rate limit: 60 requests per minute.

Authorizations

apiKey

Parameters

Path Parameters

campaignId

required

string

The campaign’s id.

Request Body^required

application/json

object

participantRef

required

string

>= 1 characters <= 200 characters

idempotencyKey

required

string

>= 8 characters <= 200 characters

tierId

The prize to give. Defaults to the first prize.

string

>= 1 characters <= 64 characters

Example

{
  "participantRef": "user_48213",
  "idempotencyKey": "goodwill-ticket-5521"
}

Responses

201

The coupon given.

application/json

object

grantId

required

string

participantRef

required

string

code

required

The full code.

string

expiresAt

required

string | null format: date-time

Example

{
  "grantId": "0192f3a1-0000-7000-8000-000000073002",
  "participantRef": "user_48213",
  "code": "COFFEE-9P4X",
  "expiresAt": "2026-11-04T10:00:00.000Z"
}

Headers

X-RateLimit-Limit

integer

Requests allowed in the current window.

X-RateLimit-Remaining

integer

Requests left in the current window.

400

The request is not valid. details lists each field that failed, where there is one.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request json.",
    "details": [
      {
        "path": "name",
        "message": "Too small, expected string to have >=1 characters"
      }
    ]
  }
}

401

The API key is missing, malformed or revoked.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

402

Your plan does not include this feature, or you have reached a plan limit.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "upgrade_required",
    "message": "Rewards is not included in your plan. Ask whoever manages your account to add it."
  }
}

403

The API key does not carry the permission this needs, or the request is not allowed.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow this (draws.run)."
  }
}

404

Nothing with that id exists in your account.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Channel 0192f3a1-0000-7000-8000-00000000c009 not found."
  }
}

409

The request clashes with the current state. The message says what to change.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "conflict",
    "message": "An archived campaign cannot be edited. Restore it first, then make the change."
  }
}

429

Rate limit exceeded. Wait for Retry-After seconds.

application/json

object

error

required

object

code

required

Stable and safe to branch on.

invalid_request (400): the request is not valid.
unauthorized (401): missing, malformed or revoked API key.
upgrade_required (402): not in your plan, or a plan limit is reached.
forbidden (403): the key lacks a permission, or the action is not allowed.
not_found (404): nothing with that id in your account.
conflict (409): clashes with the current state.
confirmation_required (409): repeat with confirm=true. Folder deletion only.
rate_limited (429): wait for Retry-After seconds.
internal_error (500) and service_unavailable (503): try again later.

string

Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable

message

required

Written for a person. May change; do not parse it.

string

details

One of:

Array<object>
object

Array<object>

object

path

required

The failing field, dot separated, such as prize.label.

string

message

required

string

Example

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 30 requests per 60s."
  }
}

Headers

Retry-After

integer

Seconds to wait before trying again.

Grant a coupon

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example

Responses

201

Example

Headers

400

Example

401

Example

402

Example

403

Example

404

Example

409

Example

429

Example

Headers

Request Body^required