Skip to main content

Manage item revocations with third-party stores

Last updated on November 4, 2026

Overview​

The AccelByte Gaming Services (AGS) Revocation service can be integrated with third-party stores and use the service's logic to synchronize and revoke items from player inventories. As part of the integration, you need to set up a server to act as the middleware to map the store's order data to AGS's revocation endpoints.

info

See also Manage item fulfillments with third-party stores to learn about granting items to players through integrated third-party stores.

This article walks you through how to manage item revocations with third-party stores.

Prerequisites​

  • User authentication: Make sure you have implemented user authentication and have valid user IDs for the players.
  • Access token for API endpoints: Ensure you have the necessary access token and permissions to access the Fulfillment and Revocation endpoints.
  • Middleware setup: Set up a middleware server to map and transform the third-party store's order data to the AGS API request format.
  • Item configuration: Configure the items in AGS that will be granted, ensuring they match the items sold in the third-party store.
  • Inventory integration: Ensure that the Inventory service integration with the Commerce service is not enabled to prevent unexpected entitlement updates.
  • Revocation configuration: Configure your revocation rules based on how you want to handle specific revocation scenarios, such as handling virtual currency and other consumable item revocations.

Supported item types​

The third-party revocation method supports the following item types:

  • Durable and consumable in-game items
  • Bundle
  • Coin
  • Media
  • Option box
  • Loot box
important
  • Inactive items can be revoked. Item status alone does not determine revocation eligibility. Missing items and consumed entitlements can cause failures.
  • If a loot box or option box has been opened, its entitlement is consumed and its revocation fails.
  • SUBSCRIPTION, SEASON, and EXTENSION grants do not support transaction revocation. They remain granted and appear in the failed-item list; retrying cannot make an unsupported item type revocable.

Handling virtual currency and other consumable item revocations​

Revoking virtual currency and other consumable items can be complicated and prone to player exploitation. We recommend configuring your revocation strategy as follows:

  • Virtual currency: If the item being revoked is a virtual currency or any other consumable items, consider changing your revocation strategy to allow negative wallet balances. This is particularly important if the virtual currency has already been spent by the player. For example, if a player spends all their currency and then a revocation is performed, their balance may need to go negative to maintain the integrity of the game's economy.

  • Other consumable items: Revoking consumable in-game items can be challenging if they have already been used or consumed. Ensure that your revocation strategy includes clear rules for handling such scenarios to avoid inconsistencies and potential fraud.

To manage the revocation strategy, see Configure revocation rules.

API endpoint​

Use V3 for transaction revocations in an environment that supports the endpoint. Your server token needs ADMIN:NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT with UPDATE (2). Validate existing transactions before changing a legacy integration.

Revoke Fulfillment V3​

PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}/revoke revokes grants associated with the saved transaction and records the revocation state. Prefix this path with /platform when calling the environment's base URL. No request body is required.

Use the original fulfillment transaction ID. The operation uses the saved grant information, including effective bundle component quantities. It is different from revoking an individual entitlement by entitlement ID.

Handle the response​

  • HTTP 200 does not guarantee successful revocation. Check state: REVOKED means completion; REVOKE_FAILED means one or more components could not be revoked.
  • Inspect stateInfo.failedList[].error and nested stateInfo.failedList[].items[].error for the cause. Other revocable items can succeed independently.
  • After correcting a recoverable issue, repeat the same revocation request with the original transaction ID. Do not use the fulfillment retry endpoint to retry a revocation.
  • For unsupported item types, arrange the appropriate business recovery process. Do not retry indefinitely or assume the items were removed.

Sample response​

This abbreviated response shows a transaction whose revocation failed because a subscription cannot be revoked through this endpoint:

{
"namespace": "your-namespace",
"userId": "22222222222242228222222222222222",
"transactionId": "store-order-123",
"state": "REVOKE_FAILED",
"stateInfo": {
"successList": [],
"failedList": [
{
"itemId": "11111111111141118111111111111111",
"error": "Cannot revoke SUBSCRIPTION item"
}
]
}
}

The error text above illustrates the failure; inspect the actual error fields returned by your environment.