Manage item fulfillments with third-party stores
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
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.
- When handling multiple invocations, repeated requests with the same
transactionIdwill not create duplicate entitlements. The system recognizes thetransactionIdand 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"
}
}