Free round campaigns

Campaign status

GET /v1/freerounds/{id} returns the campaign as it stands now. POST and GET responses contain the request body fields plus the following:

Safe retries

If you send a reference, you can safely retry the same request after a timeout. The same reference with the same content returns the first campaign with 200 and already_processed: true; you get the same campaign even if it was cancelled in the meantime; approval_id is returned while the approval is still pending. The order of games and players, a repeated player and the way the amount is written (0.5, 0.50) do not count as different content. The same reference with different content returns 409 REFERENCE_CONFLICT and no campaign is created. References are separate for Test and Live. A request rejected by validation before the campaign is written does not use up its reference. One exception: if no player can be granted (PLAYERS_REQUIRED), the campaign stays as a draft (with your reference, if you sent one); a retry with the same reference returns that draft, and every retry without a reference leaves a new draft. Cancel the draft with DELETE. X-Request-Id records expire, a reference does not.

{
  "id": "cmp_mrd_aralik",
  "name": "Aralık Hoş Geldin",
  "site_id": "site_mrd01",
  "template_id": null,
  "games": ["sultans-ember"],
  "spins": 20,
  "bet_value": 0.20,
  "currency": "USD",
  "players": ["u_88213"],
  "starts_at": "2026-12-01T00:00:00Z",
  "valid_days": 7,
  "reference": "crm-dec-welcome-88213",
  "status": "scheduled",
  "spins_used": 0,
  "won_total": 0.00,
  "already_processed": true
}

{
  "code": "REFERENCE_CONFLICT",
  "message": "A campaign with different content was already created with this reference.",
  "request_id": "req_01HF3R1C",
  "details": { "reference": "crm-dec-welcome-88213" }
}

Cancelling a campaign

DELETE /v1/freerounds/{id} cancels the campaign and every pending or active grant, and returns 204 with no body. If a player has an open round, the win of that round is still paid. The campaign.finished webhook is sent with status: cancelled. If the campaign started in the meantime, you get 409 CAMPAIGN_CHANGED: retry.

Player grants

Every player in a campaign has their own grant with its own status. Only an active grant gives spins; a free round bet on a grant in any other status is rejected by Boss Hub and never reaches your wallet.

Adding players

POST /v1/freerounds/{id}/players adds players to a draft, scheduled or open campaign, up to 100 per request. The response is 200 with a result per player: added a new grant, exists the player already has a grant in this campaign (grants do not multiply, status is the existing grant’s status), failed no grant was given. failed reasons: CURRENCY_NOT_SUPPORTED none of the campaign’s games supports the player’s currency or there is no exchange rate, BET_INVALID the spin value rounds down to zero in the player’s currency, BET_NOT_OFFERED the converted value is not one of the provider’s bet values, PROVIDER_REJECTED: … the provider rejected the player. Top-level fields: added new grants written in this request, failed failures in this request, total valid grants now in the campaign (cancelled and failed excluded). A player with a record gets a grant in their own currency; a player with no record yet gets the campaign currency. The same X-Request-Id returns the first response.

{
  "added": 1,
  "failed": 1,
  "total": 2,
  "items": [
    { "player_id": "u_90412", "result": "added", "status": "pending", "reason": null },
    { "player_id": "u_88213", "result": "exists", "status": "pending", "reason": null },
    { "player_id": "u_77120", "result": "failed", "status": null, "reason": "CURRENCY_NOT_SUPPORTED" }
  ]
}

Listing players

GET /v1/freerounds/{id}/players returns the campaign’s grants. For the next page, send the next_cursor value of the response as cursor; null means the list has ended.

{
  "items": [
    {
      "player_id": "u_88213",
      "status": "active",
      "currency": "USD",
      "spins_left": 38,
      "won_total": 38.40,
      "expires_at": "2026-11-30T23:59:59.999Z",
      "cancelled_at": null,
      "fail_reason": null
    }
  ],
  "next_cursor": null
}

Cancelling a single player

DELETE /v1/freerounds/{id}/players/{player_id} cancels the player’s unused spins and returns 204. The win of an open round is still paid. Only a pending or active grant can be cancelled; others get 409 GRANT_CLOSED with the grant’s status in details.status. In a campaign whose grants are run by the provider, the cancellation is passed on to the provider; if the provider cannot cancel a single player you get 409 PROVIDER_CANCEL_UNSUPPORTED and can cancel the whole campaign instead.

Effect on the wallet

• A free round bet arrives through bet with is_freeround: true, campaign_id set and amount: 0. Do not debit the balance. The spin value is in the freeround_bet_value field.
• The win arrives through a normal win; credit it to the balance.
• A spin is used up when the bet is OK and comes back when a rollback is OK. A rollback refunds no cash.
• A bet on a cancelled or expired grant never reaches you: Boss Hub rejects it.

Error codes