Last Updated: 9/22/2021, 7:40:10 AM

# Fulfillment

# Overview

Fulfillment is the service which 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.

# How It Works

Fulfillment works with other Commerce services to distribute items to your players. First, the Orders service will send information about the 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.

Note that each type of item has a slightly different fulfillment process. The diagrams below show the sequence flow and service dependencies for each item type.

# Item Fulfillment

The diagram below shows how item orders are fulfilled.

fulfillment

# Coin Fulfillment

The diagram below shows how coin orders are fulfilled. For coins, the Wallet service is called to store the coins in the player’s wallet.

fulfillment

# Code Redemption

This diagram shows how an item is granted to a player after they redeem a code.

fulfillment

# Implementing Fulfillments using the SDK

# 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

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

# Managing Fulfillment using API

You can also use our API endpoints to manage players’ fulfillment.

# Query the Fulfillment History

You can retrieve your game’s fulfillment history by following the steps below.

  1. Use the Query Fulfillment History: GET /admin/namespaces/{namespace}/fulfillment/history endpoint.
  2. Input the Publisher Namespace.
  3. Choose the desired fulfillment Status. Choose Success if you want to display only successful fulfillments and Fail to display failed fulfillments. If you leave this field blank ...
  4. Input the Offset if you want the history to be paginated. The offset determines the first line of data retrieved. This field can be left empty if you want to return the entire history.
  5. Input the Limit if you want the history to be paginated. The limit determines the last line of data retrieved. If you left Offset empty, leave this empty too.

Upon successful request, the desired fulfillment history will be retrieved.

# Fulfill an Item

Follow the steps below to fulfill an item.

  1. Use the Fulfill Item: POST /admin/namespaces/{namespace}/users/{userId}/fulfillment endpoint.
  2. Input the Publisher Namespace.
  3. Input the User ID of the player who will receive the fulfillment.
  4. Fill out the Request Body:
    • Input the Item ID.
    • Input the Quantity of the item you want to fulfill.
    • Input the order number in orderNo field.
    • Input the Source of the entitlement. For example, the source could be a Purchase or Promotion.
    • Input the Region of the item. This should be the same as the player’s region.
    • Input the Language of the item. This should be the same as the player’s language.

Upon successful request, the player will receive the item.

# Redeem a Campaign Code

Follow these steps to redeem a campaign code for a user.

  1. Use the Redeem Campaign Code: POST /public/namespaces/{namespace}/users/{userId}/fulfillment/code endpoint.
  2. Input the Publisher Namespace.
  3. Input the User ID of the player who will receive the fulfillment.
  4. Fill out the Request Body:
    • Input the Code field with the campaign code.
    • Input the player’s Region.
    • Input the player’s Language.

You can read more about Code Redemption in the Player Portal and Launcher guides.