Manage item fulfillments with third-party stores
Overview
Use the AccelByte Gaming Services (AGS) Fulfillment service to grant items purchased through a third-party store. Your middleware maps the store's validated order data to an AGS fulfillment transaction.
Use V3 for new grant and retry integrations. The legacy V1 grant and reward endpoints, V2 reward endpoint, and V2 transaction grant, retry, and revocation endpoints are deprecated. They remain available during migration. Validate compatibility before changing an existing integration.
For revocations, see Manage item revocations with third-party stores.
Prerequisites
- Your target environment supports the V3 endpoints shown below.
- Your middleware validates the third-party purchase and resolves the correct AGS player and namespace.
- Your server access token has
ADMIN:NAMESPACE:{namespace}:USER:{userId}:FULFILLMENTwithUPDATE(2) for grants, retries, and revocations. The legacyCREATEpermission alone is insufficient. - Your catalog items match the products sold by the third-party store.
- If you use the Inventory integration, validate its item and entitlement behavior before migrating.
Supported item types
V3 supports in-game items, bundles, coins, media, option boxes, loot boxes, subscriptions, Season Pass and Season Tier items, and extension items, subject to their configuration requirements.
- Inactive items, bundles, and bundle components can be granted. Store availability is separate from fulfillment eligibility.
SUBSCRIPTIONrequiresquantity: 1and eitherendDateorduration. Subscriptions cannot be bundled.endDatetakes precedence; without it,durationis measured in seconds and converted to whole days to create or extend a platform subscription.SUBSCRIPTION,SEASON, andEXTENSIONsupport grants but do not support transaction revocation. Do not use them in a workflow that requires automatic rollback through the revocation endpoint.- Partial success is possible, including within a bundle. Inspect the transaction result instead of assuming that the request is all-or-nothing.
API endpoints
Use Fulfillment V3 to grant items and Retry Fulfillment V3 to retry saved transactions. The existing Admin Query Fulfillment V2 endpoint remains available for transaction queries.
Fulfillment V3
PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId} grants items and records the transaction state. Prefix this path with /platform when calling the environment's base URL.
Persist a unique transactionId for each logical grant. Reuse it with the same payload for retries. Use a new ID for a genuinely new purchase or reward, even when its item and quantity match a previous grant. Do not reuse IDs from legacy transactions as an implicit migration strategy; reconcile existing transactions before switching their workflow.
Parameters
The request body contains an items array with at least one item. Each item accepts the following fields:
| Parameter | Description |
|---|---|
itemId / itemSku | Provide at least one. When both are provided, itemId takes precedence. |
quantity | Required positive integer. Must be 1 for SUBSCRIPTION. |
orderNo | Optional third-party order reference. This does not replace transactionId. |
source | Grant source, such as PURCHASE or REWARD. |
startDate, endDate | Optional entitlement dates in ISO 8601 format. |
duration | Duration in seconds; ignored when endDate is present. |
origin | Balance origin for coin grants. |
entitlementOrigin | Origin for other entitlements. |
metadata | Additional fulfillment data. Non-coin metadata is available in the EntitlementGranted event; coin metadata appears in wallet history. |
overrideBundleItemQty | Optional map of bundle component item IDs to quantities per bundle. Zero excludes a component; omitted components keep their catalog quantities. These quantities are multiplied by the parent quantity and saved for retries and revocation. |
The published SDK versions shown in Implement Fulfillment on a Game Server support basic V3 grants. Their generated request models may not expose newer fields such as overrideBundleItemQty. Use REST for such fields unless your installed SDK explicitly supports them.
Sample request
Replace the item ID with the ID from your catalog:
{
"items": [
{
"itemId": "11111111111141118111111111111111",
"quantity": 3,
"source": "PURCHASE",
"orderNo": "store-order-123",
"metadata": {
"externalOrderId": "store-order-123"
}
}
]
}
Handle the response
HTTP 200 means the request returned a transaction result; it does not guarantee every item was granted.
state: FULFILLEDmeans the transaction completed.state: FULFILL_FAILEDmeans one or more items or bundle components failed. InspectstateInfo.failedList[].errorand nestedstateInfo.failedList[].items[].error.- Summary arrays describe grants performed by the current invocation. A repeated request for a completed transaction can return empty summaries. Do not interpret this as a failed grant.
Retry Fulfillment V3
PUT /v3/admin/namespaces/{namespace}/users/{userId}/fulfillments/{transactionId}/retry retries a saved transaction without requiring the original request body. Alternatively, repeat the original grant with the same transaction ID and payload.
Inspect the failure before retrying. Correct configuration errors first. V3 skips successful components whose state has been saved and uses the saved effective bundle quantities. Do not issue a new transaction for the entire order merely because some components failed.
Asset writes and fulfillment state persistence are not atomic. After an interruption or an ambiguous network failure, reconcile the transaction and granted assets before retrying. V3 does not provide an unconditional exactly-once guarantee.
For supported items, use Manage item revocations with third-party stores when your business workflow requires revocation. Revocation is a separate operation and can also partially fail.
Admin Query Fulfillment V2
GET /v2/admin/namespaces/{namespace}/fulfillments queries transaction state. This endpoint is not deprecated by the V3 migration. It requires ADMIN:NAMESPACE:{namespace}:FULFILLMENT with READ (1).
| Parameter | Description |
|---|---|
transactionId | Filter by the persisted transaction ID. |
userId | Filter by player ID. |
state | FULFILLED, FULFILL_FAILED, REVOKED, or REVOKE_FAILED. |
startTime | Inclusive start time in ISO 8601 format. |
endTime | Exclusive end time in ISO 8601 format. |
offset | Pagination offset; defaults to 0. |
limit | Page size; defaults to 20. |
The following abbreviated response shows a completed transaction. Historical execution details are separate from the summaries returned by a grant invocation.
{
"data": [
{
"namespace": "your-namespace",
"userId": "22222222222242228222222222222222",
"transactionId": "store-order-123",
"state": "FULFILLED",
"items": [
{
"itemId": "11111111111141118111111111111111",
"quantity": 3
}
],
"stateInfo": {
"successList": [
{"itemId": "11111111111141118111111111111111"}
],
"failedList": []
}
}
]
}