Skip to main content

Manage item fulfillments with third-party stores

Last updated on November 4, 2026

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}:FULFILLMENT with UPDATE (2) for grants, retries, and revocations. The legacy CREATE permission 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.
  • SUBSCRIPTION requires quantity: 1 and either endDate or duration. Subscriptions cannot be bundled. endDate takes precedence; without it, duration is measured in seconds and converted to whole days to create or extend a platform subscription.
  • SUBSCRIPTION, SEASON, and EXTENSION support 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:

ParameterDescription
itemId / itemSkuProvide at least one. When both are provided, itemId takes precedence.
quantityRequired positive integer. Must be 1 for SUBSCRIPTION.
orderNoOptional third-party order reference. This does not replace transactionId.
sourceGrant source, such as PURCHASE or REWARD.
startDate, endDateOptional entitlement dates in ISO 8601 format.
durationDuration in seconds; ignored when endDate is present.
originBalance origin for coin grants.
entitlementOriginOrigin for other entitlements.
metadataAdditional fulfillment data. Non-coin metadata is available in the EntitlementGranted event; coin metadata appears in wallet history.
overrideBundleItemQtyOptional 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: FULFILLED means the transaction completed.
  • state: FULFILL_FAILED means one or more items or bundle components failed. Inspect stateInfo.failedList[].error and nested stateInfo.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.

warning

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).

ParameterDescription
transactionIdFilter by the persisted transaction ID.
userIdFilter by player ID.
stateFULFILLED, FULFILL_FAILED, REVOKED, or REVOKE_FAILED.
startTimeInclusive start time in ISO 8601 format.
endTimeExclusive end time in ISO 8601 format.
offsetPagination offset; defaults to 0.
limitPage 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": []
}
}
]
}