Cancel Free Bets

Cancel the unused free bets of a previously granted reward. Use this — never /rollback — to reverse a granted-but-unused reward.

Authentication

This endpoint is authenticated by IP whitelist — your server's outbound IP must match the address registered during onboarding. The X-Marbles-Signature header is not required and is ignored if sent.

Endpoint

POST https://api.marbles.xyz/game/free-bets/rewards/cancel

Staging: https://api.stagingmarbles.io/game/free-bets/rewards/cancel.

Request

{
  "clientRewardId": "promo-winter-2025-001",
  "operatorId": "your-operator-id",
  "reason": "Player requested cancellation"
}

Success Response

{
  "reward": {
    "type": "Reward",
    "clientRewardId": "promo-winter-2025-001",
    "clientPlayerId": "player-123",
    "operatorId": "your-operator-id",
    "amount": 500000,
    "currency": "USD",
    "quantity": 2,
    "applicableGames": [],
    "meta": {},
    "status": "cancelled",
    "createdAt": "2025-06-15T14:30:00Z",
    "cancelledAt": "2025-07-01T10:00:00Z"
  },
  "freeBets": [
    {
      "id": "fb-001",
      "amount": 500000,
      "currency": "USD",
      "status": "cancelled",
      "createdAt": "2025-06-15T14:30:00Z",
      "expiresAt": "2025-12-31T23:59:59Z",
      "applicableGames": []
    }
  ]
}

Cancel Rules

Only free bets with status claimable or claimed can be cancelled
If any free bet from the reward has been used, the entire reward cannot be cancelled
Cancellation is per-reward (per-player), not campaign-wide
Scheduled rewards (where startTime is in the future) can be cancelled before the free bets are generated. The reward is transitioned to cancelled and a REWARD_NOT_STARTED response is returned with no freeBets payload — treat it as a successful cancellation

Error Responses

All errors use the {"error", "details"} shape; the reward errors (404/409) additionally carry a numeric code:

Error	HTTP Code	`code`	Description
`REWARD_NOT_FOUND`	404	9001	No reward exists for the provided `clientRewardId`
`REWARD_CANNOT_BE_CANCELLED`	409	9006	At least one free bet has already been `used` — the reward cannot be cancelled
`REWARD_NOT_STARTED`	409	9007	Reward was scheduled for a future `startTime`; the free bets hadn't been generated yet. The reward has been transitioned to `cancelled` — treat this as a successful cancellation
`Internal server error`	500	—	Unexpected failure

Free-Bet Statuses

Status	Description
`claimable`	Available for the player to use
`claimed`	Player has selected but not yet placed a bet
`used`	Free bet was used to place a bet
`expired`	Free bet expired before being used
`cancelled`	Free bet was cancelled by operator