Manage item fulfillments with third-party stores

Last updated on December 18, 2024

Overview

The AccelByte Gaming Services (AGS) Revocation service can be integrated with third-party stores to synchronize and grant items to players. 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 fulfillment endpoints.

備考

See also Third-party revocation integration to learn about revoking items from player inventories through integrated third-party stores.

This article walks you through how to manage item fulfillments 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.

Supported item types

The third-party fulfillment 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 granted to players as long as the items are active in your AGS Store and in your integrated third-party store. However, if even one item in a bundle is not supported, then all the items in the entitlement cannot be fulfilled or granted to the player.

API endpoints

Item fulfillment with third-party stores are managed through the Fulfillment V2 and Admin Query Fulfillment V2 endpoints.

Fulfillment V2

The PUT /v2/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId} endpoint grants multiple items based on the provided {transactionId} and records the fulfillment status. The {transactionId} should be a unique identifier for each fulfillment request within the client's system to prevent duplicate processing.

NOTES

• When handling multiple invocations, repeated requests with the same transactionId will not create duplicate entitlements. The system recognizes the transactionId and ensures that only items that have not been fulfilled are processed.
• If a request fails, the integrator should first identify the reason for the failure (e.g., inactive items or unsupported item types). The error message in the response will help pinpoint the issue. Once the issue is resolved, the integrator can retry the fulfillment process using the same transactionId. The system will only attempt to fulfill the items that previously failed, ensuring that successful items are not duplicated. If necessary, the integrator can also reverse the action by using the Revoke Fulfillment endpoint to undo the fulfillment.

Parameters

The following table describes each parameter for Fulfillment V2 requests.

Parameter	Description	Requirement
itemId	The unique identifier for the item being fulfilled or revoked.	Required if itemSku is not present. If both are present, itemId will be used.
itemSku	The stock-keeping unit identifier for the item.	Required if itemId is not present
quantity	The number of items to be fulfilled or revoked.	Required
orderNo	The order number associated with the purchase or transaction.	Optional
source	The source of the item, such as "PURCHASE", indicating how the item was acquired.	Required
startDate	The start date for the item's entitlement, specified in ISO 8601 format.	Optional
endDate	The end date or expiry date for the item's entitlement, specified in ISO 8601 format.	Optional
duration	The duration in days for which the entitlement is valid. This is used to set the duration (related to the end date or expiry) of the entitlement.	Optional
origin	The balance origin for COIN item fulfillment. It is used to set for which wallet the virtual currency is to be granted. If not provided, it will be set to SYSTEM.	Optional
metadata	Additional properties or metadata related to the item being fulfilled or revoked. This can include custom data specific to the item. Usage: Metadata associated with non-coin items will not be visible in the Admin Portal. However, this metadata will appear in the entitlementgranted event, which you can monitor through API events. For more details, refer to the EntitlementGranted event documentation. For coin item types, the metadata will be displayed in the player's wallet history, allowing administrators to track virtual currency transactions.	Optional
entitlementOrigin	Used for other item type entitlements, indicating the origin of the entitlement. If not provided, it will be set to SYSTEM.	Optional

Sample request

{
    "items": [
        {
            "itemId": "required, if itemSku is not present, if both present itemId will be used",
            "itemSku": "required if itemId is not present",
            "quantity": 3,
            "orderNo": "optional",
            "source": "PURCHASE",
            "startDate": "optional",
            "endDate": "optional",
            "duration": 0,
            "origin": "Playstation",
            "metadata": {
                "additionalProp1": {},
                "additionalProp2": {},
                "additionalProp3": {}
            "entitlementOrigin": "Playstation",
        }
    ]
}

Admin Query Fulfillment V2

The GET /v2/admin/namespaces/{namespace}/fulfillments endpoint queries the fulfillment status based on the provided parameters. |

Parameters

The following table describes each parameter in the Admin Query Fulfillment V2 request.

Paremeter	Data Type
transactionId`	string
state	string ("FULFILLED", "REVOKED", "FULFILL_FAILED", or "REVOKE_FAILED")
userId	string
staartTime	timestamp (in ISO 8601 format)
endTime	timestamp (in ISO 8601 format)
offset	integer
limit	integer

Sample response

{
    "data": [
        {
            "id": "string",
            "namespace": "string",
            "userId": "UUID",
            "transactionId": "string",
            "state": "FULFILLED",
            "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": []
        }
    ],
    "paging": {
        "previous": "string",
        "next": "string"
    }
}