Cancel a free-round grant
POST/free-rounds/{grant_id}/cancel
Cancel a grant’s outstanding rounds at the provider. Already-played
rounds are not reversed. Requires the write scope (or the granular
free_rounds.write).
Mobule: there is no provider cancel call, and the cut-off is Mobule’s
activation of a game’s freerounds_id, not the player’s launch.
Cancelling marks every game Mobule has not activated yet cancelled on
our side, a game the player has already launched included (its
activation is then refused and the player plays without the free
rounds), and no later launch attaches it. A game Mobule has already
activated is not reversed: it is reported per game as consumed (its
rounds are in play and their win reaches your wallet, even after the
cancel), never as cancelled. A game whose activation Mobule itself
cancelled is reported cancelled: Mobule does not run those rounds, so
issue a new grant to replace them. A game whose win was already
credited stays consumed even if Mobule cancels its activation
afterwards. Once the grant is issued, whatever its status, when nothing
is left to cancel the answer is 409 not_cancellable with
grant_status and the per-game games. While the grant is still being
issued the answer is 409 issuance_in_progress with grant_status: pending_issue and the per-game games, and nothing changed: retry the
cancel once the grant is active. If the issuance stopped after
creating the grant, the grant stays pending_issue: a replay of the
issue request keeps answering 409 idempotency_in_progress, this cancel
keeps answering 409 issuance_in_progress, no launch carries its
rounds, and the expiry sweep (every 30 minutes) closes it as expired
after its end_at. Issue a new grant under a new Idempotency-Key once
it has closed: while it is pending_issue an issuance that is merely
slow can still activate it, and both grants would pay.
This endpoint’s own refusals are the flat FreeRoundError body
(error is the code, status repeats the HTTP status). The brand
selector of a platform account (sub_operator_ref, sent or omitted)
refuses with the nested Error object instead (the E60xx codes
below), and a key without the write or free_rounds.write scope gets
a flat insufficient_scope body without status.
Platform accounts must send sub_operator_ref - the same brand the
grant was issued to.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”brand-01Platform accounts only, and required for them. The brand the
grant was issued to - grants are keyed on the brand’s identity, so a
platform must name the same brand it issued to. Omitting it targets
your default brand, which means a grant issued under a named
brand will simply 404: send the ref you issued with. Sending it from
a non-platform key is a 400 (E6006); with no default brand
provisioned the call is a 409 (E6010), and under
require_sub_operator_ref omitting it is a 400 (E6005).
Omit it to get the default brand; sending it empty is a 400
(E6004), not a fallback - see sub_operator_ref on
POST /v1/sessions for why the two differ.
Responses
Section titled “Responses”Grant cancelled.
object
object
The brand selector refused (nested Error): sub_operator_ref sent empty or malformed (E6004), omitted under require_sub_operator_ref (E6005), sent from a non-platform key (E6006), or naming an unknown brand while auto-provisioning is off (E6008). A blank grant_id is the flat FreeRoundError (grant_id required).
object
object
Correlation ID for support escalation.
object
The flat error body of the free-rounds endpoints’ own refusals (those of POST /v1/free-rounds/{grant_id}/cancel, and the idempotency_* 409s of POST /v1/free-rounds), not the nested Error object a platform’s brand selector answers with: error is the machine-readable code and status repeats the HTTP status.
object
The code, e.g. grant_not_found, not_cancellable, issuance_in_progress, provider_error, provider_unavailable.
issuance_in_progress409The grant’s status (409 only).
Mobule 409 only - the state of each game of the grant.
object
Missing, invalid, or revoked API key.
object
object
Correlation ID for support escalation.
object
The key has neither the write nor the free_rounds.write scope (insufficient_scope, a flat body without status), or the brand selector refused (nested Error): the platform is at its brand cap (E6007) or the named brand is not active (E6008).
object
object
Correlation ID for support escalation.
object
object
insufficient_scopeGrant not found (grant_not_found).
The flat error body of the free-rounds endpoints’ own refusals (those of POST /v1/free-rounds/{grant_id}/cancel, and the idempotency_* 409s of POST /v1/free-rounds), not the nested Error object a platform’s brand selector answers with: error is the machine-readable code and status repeats the HTTP status.
object
The code, e.g. grant_not_found, not_cancellable, issuance_in_progress, provider_error, provider_unavailable.
issuance_in_progress409The grant’s status (409 only).
Mobule 409 only - the state of each game of the grant.
object
Not cancellable: the grant is in a terminal state (not_cancellable, with grant_status). For Mobule also whenever no game is left to cancel, whatever the issued grant’s status (not_cancellable, with grant_status and the per-game games), and while the grant is still being issued (issuance_in_progress, with grant_status and games; nothing changed: retry once the grant is active, and if its issuance stopped, issue a new grant under a new Idempotency-Key once it has closed as expired). These are the flat FreeRoundError. A platform account’s brand selector answers the nested Error instead: no default brand, or an inactive one, with sub_operator_ref omitted (E6010); the platform owns no organization yet, with a ref sent (E6009); or no identity could be allocated for a new brand (E6007).
The flat error body of the free-rounds endpoints’ own refusals (those of POST /v1/free-rounds/{grant_id}/cancel, and the idempotency_* 409s of POST /v1/free-rounds), not the nested Error object a platform’s brand selector answers with: error is the machine-readable code and status repeats the HTTP status.
object
The code, e.g. grant_not_found, not_cancellable, issuance_in_progress, provider_error, provider_unavailable.
issuance_in_progress409The grant’s status (409 only).
Mobule 409 only - the state of each game of the grant.
object
object
object
Correlation ID for support escalation.
object
The provider rejected the cancellation (provider_error, a FreeRoundError), or cancelled only some games (a FreeRoundCancelResponse with status: cancel_failed and the per-game games).
The flat error body of the free-rounds endpoints’ own refusals (those of POST /v1/free-rounds/{grant_id}/cancel, and the idempotency_* 409s of POST /v1/free-rounds), not the nested Error object a platform’s brand selector answers with: error is the machine-readable code and status repeats the HTTP status.
object
The code, e.g. grant_not_found, not_cancellable, issuance_in_progress, provider_error, provider_unavailable.
issuance_in_progress409The grant’s status (409 only).
Mobule 409 only - the state of each game of the grant.
object
object
object
The provider configuration or the cancel transition is temporarily unavailable (provider_unavailable, a FreeRoundError); retry. A platform account’s brand selector can also answer the nested Error with sub_operator_ref sent: the account’s type could not be read (E6006), or its brand count could not be read while provisioning a new brand (E6007); retry.
The flat error body of the free-rounds endpoints’ own refusals (those of POST /v1/free-rounds/{grant_id}/cancel, and the idempotency_* 409s of POST /v1/free-rounds), not the nested Error object a platform’s brand selector answers with: error is the machine-readable code and status repeats the HTTP status.
object
The code, e.g. grant_not_found, not_cancellable, issuance_in_progress, provider_error, provider_unavailable.
issuance_in_progress409The grant’s status (409 only).
Mobule 409 only - the state of each game of the grant.
object
object
object
Correlation ID for support escalation.