Set the reward

PUT

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

const url = 'https://api.keliplay.com/v1/game-instances/example/reward';
const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"tiers":[{"id":"0192f3a1-0000-7000-8000-000000071001","match":{"when":"won"},"display":{"title":"Free coffee","description":"One regular coffee at any store."},"codeStrategy":"pool"},{"match":{"when":"everyone"},"display":{"title":"10% off"},"codeStrategy":"shared"}],"grantOncePerParticipant":true,"validForSeconds":2592000}'
};

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

curl --request PUT \
  --url https://api.keliplay.com/v1/game-instances/example/reward \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "tiers": [ { "id": "0192f3a1-0000-7000-8000-000000071001", "match": { "when": "won" }, "display": { "title": "Free coffee", "description": "One regular coffee at any store." }, "codeStrategy": "pool" }, { "match": { "when": "everyone" }, "display": { "title": "10% off" }, "codeStrategy": "shared" } ], "grantOncePerParticipant": true, "validForSeconds": 2592000 }'

Replaces the campaign’s prizes, in priority order. A player receives the first prize whose match they meet.

To keep a prize and its codes, send it back with its id. A prize left out is removed, which is refused (409) while it still holds codes. A prize’s codeStrategy cannot change once it has given out coupons (409). Send null as the whole body to remove the reward.

A prize that could never be given out is refused (400): a won match on any game but Spin the Wheel, or an outcome match naming a segment the wheel does not have.

Animations on the reward page must come from your media library.

Permission: rewards.write. Plan feature: Rewards.

Authorizations

apiKey

Parameters

Path Parameters

campaignId

required

string

The campaign’s id.

Request Body^required

application/json

One of:

object
null

object

tiers

required

Prizes in priority order. A player gets the first one they match.

Array<object>

>= 1 items <= 8 items

object

An existing prize’s id, to keep it and its codes. Leave out for a new prize.

string

>= 1 characters <= 64 characters

match

required

One of:

object

when

required

Allowed value: everyone

display

required

How the prize is described to the player.

object

title

required

string

>= 1 characters <= 120 characters

description

string

<= 600 characters

termsUrl

string format: uri

<= 2048 characters

codeStrategy

required

Where the prize’s codes come from.

pool: codes you upload or generate, each given out up to its issue limit.
shared: one code given to everyone who earns the prize.
generated: a fresh code made for each player when they earn it.

string

Allowed values: pool shared generated

grantOncePerParticipant

Give each player at most one coupon from this campaign.

boolean

default: true

validForSeconds

How long a coupon stays valid after it is given. Null means no expiry.

integer | null

>= 1 <= 31536000

page

One of:

object
null

The page shown after the game. At most 20 blocks, 8 images, videos and animations, 1 video, 2 animations, 2,000 characters of text and 16 KB in all.

object

blocks

required

Array

>= 1 items <= 20 items

A block on the reward page. Any shared block type, plus:

outcome: the result of the play. Optional prefix (up to 40 characters).
coupon: the player’s coupon. Optional caption (up to 120 characters), copyable (default true) for a copy button, and show: code (the default), name (the coupon’s name) or both. A coupon with no name shows its code. The copy button appears only when the code is shown.

when is one of always (default), win or not_win.

object

required

string

>= 1 characters <= 64 characters

type

required

string

text

string

<= 600 characters

align

string

default: center

Allowed values: start center

url

An https URL, or a file from your media library.

string

<= 2048 characters

posterUrl

string

<= 2048 characters

alt

string

<= 120 characters

maxWidth

integer

>= 60 <= 720

autoplay

boolean

loop

boolean

controls

boolean

speed

number

>= 0.25 <= 2

size

string

Allowed values: sm md lg

type

required

string

Allowed values: logo heading text outcome coupon image video lottie spacer divider

when

string

default: always

Allowed values: always win not_win

prefix

string

<= 40 characters

caption

string

<= 120 characters

show

For coupon. What the player sees.

string

default: code

Allowed values: code name both

copyable

boolean

default: true

Example

{
  "tiers": [
    {
      "id": "0192f3a1-0000-7000-8000-000000071001",
      "match": {
        "when": "won"
      },
      "display": {
        "title": "Free coffee",
        "description": "One regular coffee at any store."
      },
      "codeStrategy": "pool"
    },
    {
      "match": {
        "when": "everyone"
      },
      "display": {
        "title": "10% off"
      },
      "codeStrategy": "shared"
    }
  ],
  "grantOncePerParticipant": true,
  "validForSeconds": 2592000
}

Responses

200

The saved reward, or null when removed.

application/json

object

reward

required

One of:

object
null

object

tiers

required

Array<object>

One prize, with its stock.

object

required

string

match

required

One of:

object

when

required

Allowed value: everyone

display

required

How the prize is described to the player.

object

title

required

string

>= 1 characters <= 120 characters

description

string

<= 600 characters

termsUrl

string format: uri

<= 2048 characters

codeStrategy

required

Where the prize’s codes come from.

pool: codes you upload or generate, each given out up to its issue limit.
shared: one code given to everyone who earns the prize.
generated: a fresh code made for each player when they earn it.

string

Allowed values: pool shared generated

coupons

required

Codes stored for this prize.

integer

couponsRemaining

required

Codes that can still be given out. Null when a code has no issue limit.

integer | null

granted

required

Coupons given out for this prize.

integer

grantOncePerParticipant

required

boolean

validForSeconds

required

integer | null

page

required

One of:

object
null

The page shown after the game. At most 20 blocks, 8 images, videos and animations, 1 video, 2 animations, 2,000 characters of text and 16 KB in all.

object

blocks

required

Array

>= 1 items <= 20 items

A block on the reward page. Any shared block type, plus:

outcome: the result of the play. Optional prefix (up to 40 characters).
coupon: the player’s coupon. Optional caption (up to 120 characters), copyable (default true) for a copy button, and show: code (the default), name (the coupon’s name) or both. A coupon with no name shows its code. The copy button appears only when the code is shown.

when is one of always (default), win or not_win.

object

required

string

>= 1 characters <= 64 characters

type

required

string

text

string

<= 600 characters

align

string

default: center

Allowed values: start center

url

An https URL, or a file from your media library.

string

<= 2048 characters

posterUrl

string

<= 2048 characters

alt

string

<= 120 characters

maxWidth

integer

>= 60 <= 720

autoplay

boolean

loop

boolean

controls

boolean

speed

number

>= 0.25 <= 2

size

string

Allowed values: sm md lg

type

required

string

Allowed values: logo heading text outcome coupon image video lottie spacer divider

when

string

default: always

Allowed values: always win not_win

prefix

string

<= 40 characters

caption

string

<= 120 characters

show

For coupon. What the player sees.

string

default: code

Allowed values: code name both

copyable

boolean

default: true

Example

{
  "reward": {
    "tiers": [
      {
        "id": "0192f3a1-0000-7000-8000-000000071001",
        "match": {
          "when": "won"
        },
        "display": {
          "title": "Free coffee",
          "description": "One regular coffee at any store."
        },
        "codeStrategy": "pool",
        "coupons": 0,
        "couponsRemaining": 0,
        "granted": 0
      }
    ],
    "grantOncePerParticipant": true,
    "validForSeconds": 2592000,
    "page": {
      "blocks": [
        {
          "id": "heading",
          "type": "heading",
          "when": "always",
          "text": "Free coffee",
          "align": "center"
        },
        {
          "id": "outcome",
          "type": "outcome",
          "when": "always"
        },
        {
          "id": "coupon",
          "type": "coupon",
          "when": "always",
          "copyable": true
        }
      ]
    }
  }
}

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."
  }
}

Set the reward

Authorizations

Parameters

Path Parameters

Request Bodyrequired

Example

Responses

200

Example

400

Example

401

Example

402

Example

403

Example

404

Example

409

Example

Request Body^required