Skip to main content

Assign rewards on-demand

This endpoint lets you grant a player rewards on-demand (anytime), without waiting for a mission/opponent flow.

It’s a great integration point if you have other systems (CRM, wallet, sportsbook, payment/transactions, VIP program) that should be able to trigger rewards in the SavageTech gamification layer.

Endpoint​

  • Method: POST
  • Path: /api/v1/players/{playerId}/reward
    (Note: the path uses singular reward, not “rewards”.)
  • Auth: User JWT or app credentials with access to the vendor.

What you can grant​

You can grant one or more items in a single call:

  • Currency
  • Equipment
  • Loot chests
  • External rewards (integrates with your CRM/API via the bonus engine) — see External rewards

Request body​

Top-level fields:

FieldTypeRequiredDescription
itemsarrayYesOne or more reward items.
customMessagestringNoOptional message shown to the player (where supported).

Reward item shapes​

  • Currency
{ "type": "Currency", "amount": 100 }
  • Equipment
{ "type": "Equipment", "equipmentId": "eq-helm-1" }
  • Loot chest
{ "type": "LootChest", "lootChestId": "daily-chest" }
  • External
{ "type": "External", "externalRewardId": "welcome-bonus-10" }

Examples​

curl: grant multiple rewards​

curl -X POST "https://your-api/api/v1/players/player-123/reward" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "Currency", "amount": 100 },
      { "type": "Equipment", "equipmentId": "eq-helm-1" },
      { "type": "LootChest", "lootChestId": "daily-chest" }
    ],
    "customMessage": "Reward granted!"
  }'

curl: grant an external reward (CRM/API integration)​

curl -X POST "https://your-api/api/v1/players/player-123/reward" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "type": "External", "externalRewardId": "welcome-bonus-10" }
    ],
    "customMessage": "You unlocked a bonus!"
  }'

JavaScript: trigger rewards from your backend​

This is a typical pattern for integrating your systems: your backend decides a player should get a reward, then calls the SavageTech API.

export async function grantSavageTechReward(playerId: string) {
  const response = await fetch(`https://your-api/api/v1/players/${playerId}/reward`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${process.env.SAVAGE_TECH_TOKEN}`,
    },
    body: JSON.stringify({
      items: [{ type: 'Currency', amount: 50 }],
      customMessage: 'Thanks for your purchase!',
    }),
  });

  if (!response.ok) {
    const body = await response.text();
    throw new Error(`Failed to grant reward: ${response.status} ${body}`);
  }

  return response.json();
}

Responses and errors​

  • 200: Reward(s) granted successfully.
  • 400: Invalid JSON/body (e.g. empty items), invalid IDs, or player is deactivated (rewards cannot be granted).
  • 401/403: Authentication/authorization failure.
  • 404: Player not found.

Best practices​

  • Validate the IDs you use (equipmentId, lootChestId, externalRewardId) are for the same vendor.
  • Treat the call as a backend-to-backend integration point (don’t expose sensitive credentials to the browser).
  • If you plan to retry on network errors, make your own “grant reward” workflow idempotent (e.g. store a request id on your side).