Manage item revocations with third-party stores

Last updated on October 4, 2024

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 will need 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 to 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

• Whether as individual items or as parts of bundles, the supported item types can be successfully revoked as long as they're active in your AGS Store and in your integrated third-party store. Even disabled items can still be revoked as long as they exist in both store platforms. However, deleted items, or items that no longer exist in both store platforms, cannot be revoked.
• If loot boxes and option boxes are opened and the contents are revealed, the entitlement is considered consumed and revocation will fail.

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

Item fulfillment through third-party stores are managed through the Revoke Fulfillment V2 endpoint.

Revoke Fulfillment V2

The PUT /v2/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}/revoke endpoint revokes items based on the provided transaction ID and records the revocation status.

note

If the request fails, correct the issue and retry the revocation using the same transactionId. The error message in the response will help pinpoint the issue.

Sample response

{
    "id": "string",
    "namespace": "string",
    "userId": "UUID",
    "transactionId": "string",
    "state": "REVOKED",
    "items": [
        {
            "itemId": "UUID",
            "itemSku": "string",
            "itemType": "enum",
            "quantity": 1
        }
    ],
    "stateInfo": {
        "successList": [
            {
               "itemId": "item-id-1",
               "itemSku": "item-sku-1"
            },
            {
               "itemId": "bundle-item-id-2",
               "itemSku": "bundle-item-sku-2",
               "Items": {
                               "itemId: "item-id-3",
                               "quantity": 3
               }
            }
        ],
        "failedList": [
             {
               "itemId": "item-id-4",
               "itemSku": "item-sku-4",
               "error": "failure reason"
            },
            {
               "itemId": "bundle-item-id-5",
               "itemSku": "bundle-item-sku-5",
               "Items": {
                               "itemId: "item-id-6",
                               "quantity": 6,
                               "error": "failure reason"
               }
            }
        ]
    },
    "entitlementSummaries": [],
    "creditSummaries": [],
    "subscriptionSummaries": []
}