Fulfillment

Last updated on 15 July, 2022 1:44 AM

Overview

AccelByte Cloud's Fulfillment service is used to grant entitlements to players that they have purchased or otherwise earned. If a player purchases an item or redeems a promotional code, the Fulfillment service works to ensure that they receive that item immediately.

Fulfillment works with other Cloud Commerce services to distribute items to your players. First, the Orders service will send information about a newly placed order to the Fulfillment service. Then, the Entitlement service and Catalog service work together to check the availability of the item. If the item is available, it will be granted to the player.

Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage fulfillments in the Admin Portal. For a full list of permissions that impact fulfillment management, see the Platform/Commerce tab of the permissions reference.

Usage	Permission Tag	Action
Query fulfillment histories	ADMIN:NAMESPACE:{namespace}:FULFILLMENT	Read
Fulfill Item	NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT	Create
Redeem campaign code	NAMESPACE:{namespace}:USER:{userId}:FULFILLMENT	Create

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

Manage Fulfillment in the Admin Portal

View a Fulfillment Log

You can open a fulfillment log in the Admin Portal to see if that fulfillment was successful.

1. In the Admin Portal, choose the desired namespace.

   TIP

   Choose the Publisher Namespace to see all of the fulfillment logs from all of your namespaces.

   Choose a Game Namespace to see the fulfillment logs from only that namespace.

   

2. In the Admin Portal, go to the E-Commerce section and open the Fulfillment menu.

   

3. On the Fulfillment Logs page, you can see a list of all of the fulfillment logs. You can filter the fulfillment logs by Fulfillment Status, either Successful or Failed. You can also search for a particular log using the player's User ID.

   

4. To open a log, click View in that log's Details column.

   

Implement Fulfillment using the Client SDKs

Code Redemption

A player can redeem a campaign code to receive entitlements, such as games, in-game items, or coins. To redeem a code, call RedeemCode from the Fulfillment API. The code will be redeemed and the player will receive their entitlements under the following conditions:

• The code exists in the game namespace
• The maximum redemption limit hasn't been reached
• The time and date of the redemption falls within the redemption period

Unreal Engine

FString Code = FString("MyRedeemCode");
FString Region = FString("US"); // Leave it blank if you want to use the default value from user token
FString Language = FString("en"); // Leave it blank if you want to use the default value from user token
FRegistry::Fulfillment.RedeemCode(Code, Region, Language, THandler<FAccelByteModelsFulfillmentResult>::CreateLambda([](const FAccelByteModelsFulfillmentResult& Result)
{
    // Do something if RedeemCode has been successful
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if RedeemCode has an error
    UE_LOG(LogTemp, Log, TEXT("Error RedeemCode, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

string code = "MyRedeemCode";
        string region = "US";
        string language = "en";

        AccelBytePlugin.GetFulfillment().RedeemCode(code, region, language, result =>
        {
            if (result.IsError)
            {
                // Do something if RedeemCode has an error
                Debug.Log($"Error RedeemCode, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if RedeemCode has been successful
            }
        });

Game Server Grants Item to Player

The FulfillUserItem() function can be used to allow the game server to trigger the Fulfillment service and grant an item to a player. This can be used to immediately grant a player an item when they earn a particular achievement, or to grant every player in a match a special item for a particular game mode but have that item disappear from the player's inventory when the match is over.

Unreal Engine

#include "GameServerApi/AccelByteServerEcommerceApi.h"

FString UserId = FString("SomeUserId");
FAccelByteModelsFulfillmentRequest FulfillmentRequest;
FulfillmentRequest.ItemId = FString("SomeItemId");
FulfillmentRequest.OrderNo = FString("SomeOrderNo");
FulfillmentRequest.Language = FString("en");
FulfillmentRequest.Region = FString("US");
FulfillmentRequest.Quantity = 1;
FulfillmentRequest.Source = EAccelByteItemSource::ACHIEVEMENT;

FRegistry::ServerEcommerce.FulfillUserItem(UserId, FulfillmentRequest, THandler<FAccelByteModelsFulfillmentResult>::CreateLambda([](const FAccelByteModelsFulfillmentResult& Result)
{
    // Do something if FulfillUserItem has been successful
}),
FErrorHandler::CreateLambda([](int32 ErrorCode, const FString& ErrorMessage)
{
    // Do something if FulfillUserItem has an error
    UE_LOG(LogTemp, Log, TEXT("Error FulfillUserItem, Error Code: %d Error Message: %s"), ErrorCode, *ErrorMessage);
}));

Unity

using AccelByte.Server;

string userId = "SomeUserId";
        FulfillmentRequest fulfillmentRequest = new FulfillmentRequest
        {
            itemId = "SomeItemId",
            orderNo = "SomeOrderNo",
            language = "en",
            region = "US",
            quantity = 1,
            source = ItemSource.ACHIEVEMENT
        };

        AccelByteServerPlugin.GetEcommerce().FulfillUserItem(userId, fulfillmentRequest, result =>
        {
            if (result.IsError)
            {
                // Do something if FulfillUserItem has an error
                Debug.Log($"Error FulfillUserItem, Error Code: {result.Error.Code} Error Message: {result.Error.Message}");
            }
            else
            {
                // Do something if FulfillUserItem has been successful
            }
        });

Related Concepts

• Read about our Cloud Entitlements service to learn more about managing player entitlements.
• See our Cloud Orders documentation to learn more about integrating our Orders service into your game and managing player orders from the Admin Portal.
• Learn more about how to create codes that players can redeem for games or items by reading our Cloud Code Redemption documentation.