Quick Start Example

This page shows a complete freebet lifecycle from award to settlement with full request/response examples.

Complete Flow: Award → Bet → Settle Win

Let’s walk through a typical freebet scenario where a player receives a 1000 USD freebet, places a bet with odds 4.0, and wins.

Step 1: Award Freebet

GR8 Tech grants a 1000 USD freebet to the player.

Request:


{
  "currency": "USD",
  "platform": "sport",
  "id": "e09751f8-bf51-48e4-9883-21eaa720920f-a37f67df-4969-4296-a38f-754384128df5",
  "type": "award",
  "initiatedAt": "2024-06-28T13:09:33.000Z",
  "createdAt": "2024-06-28T13:09:33.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet award",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0", // Freebet amount granted to user
    "locked": "0.0"
  }
}

Your Response:


{
  "currency": "USD",
  "platform": "sport",
  "id": "e09751f8-bf51-48e4-9883-21eaa720920f-a37f67df-4969-4296-a38f-754384128df5",
  "type": "award",
  "initiatedAt": "2024-06-28T13:09:33.000Z",
  "createdAt": "2024-06-28T13:09:33.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet award",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0",
    "locked": "0.0"
  },
  "balances": {
    "cash": "5000.0",
    "bonus": "1000.0",
    "locked": "0.0",
    "retract": "0.0"
  },
  "alreadyProcessed": false
}

What happened:

Player’s bonus balance increased by 1000 USD
Player now has an active freebet they can use

Step 2: Place Bet

Player places a bet using the freebet. Bet amount: 1000 USD, Odds: 4.0

Request:


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0", // Freebet amount used for bet
    "locked": "0.0"
  }
}

Your Response:


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474",
  "type": "withdrawal",
  "initiatedAt": "2024-06-28T13:10:31.000Z",
  "createdAt": "2024-06-28T13:10:31.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "0.0",
    "bonus": "1000.0",
    "locked": "0.0"
  },
  "balances": {
    "cash": "5000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "0.0"
  },
  "alreadyProcessed": false
}

What happened:

Player’s bonus balance decreased by 1000 USD
Bet is now pending (waiting for event result)
Freebet is consumed and cannot be used again

Step 3: Settle Win

The bet wins! Total payout: 1000 × 4.0 = 4000 USD. Player receives: 4000 - 1000 = 3000 USD.

Request:


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581699813782_0",
  "type": "deposit",
  "initiatedAt": "2024-06-28T13:35:00.000Z",
  "createdAt": "2024-06-28T13:35:00.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  }
}

Your Response:


{
  "currency": "USD",
  "platform": "sport",
  "id": "0a497028-004d-4b46-b8ba-655757a72474_1719581699813782_0",
  "type": "deposit",
  "initiatedAt": "2024-06-28T13:35:00.000Z",
  "createdAt": "2024-06-28T13:35:00.000Z",
  "context": {
    "product": "sportsbook",
    "reason": "settle freebet",
    "betId": "0a497028-004d-4b46-b8ba-655757a72474",
    "SportBonusOfferId": "a37f67df-4969-4296-a38f-754384128df5",
    "SportBonusPlayerOfferId": "e09751f8-bf51-48e4-9883-21eaa720920f"
  },
  "amountBreakdown": {
    "cash": "3000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  },
  "balances": {
    "cash": "8000.0",
    "bonus": "0.0",
    "locked": "0.0",
    "retract": "1000.0"
  },
  "alreadyProcessed": false
}

What happened:

Player’s cash balance increased by 3000 USD (winnings excluding freebet amount)
Original freebet amount (1000 USD) moved to retract balance
Freebet lifecycle is complete

Balance Changes Summary

Step	Cash	Bonus	Retract	Description
Initial	5000	0	0	Player’s starting balance
After Award	5000	1000	0	Freebet granted
After Bet	5000	0	0	Freebet used for bet
After Settle	8000	0	1000	Winnings paid, freebet to retract

Net result: Player gained 3000 USD cash (profit from the bet).

Key Takeaways

You don’t calculate winnings - GR8 Tech sends you the exact amounts in amountBreakdown
Apply amounts as received - Add/subtract values from corresponding balance types
Return updated balances - Always include current balances in your response
Implement idempotency - Same transaction id must return the same response

What’s Next?

How Freebet Works - Understand the mechanics in detail
Transaction Reference - Complete reference for all transaction types
Lifecycle and Error Handling - Edge cases and error scenarios