Request and Fulfill Entitlements

Overview

Once a player has linked their Amazon account to a game account, they're ready to claim content on the Prime Gaming website and receive it in your game! Claiming an offer creates an entitlement for that player to the offer's content, and fulfillment is the process by which you deliver upon that entitlement. Together, requesting Prime Gaming entitlements and fulfilling them to customers is referred to as content delivery.

The following is a high-level overview of the content delivery process, with each step described in more detail below:

1. Preparing your content. Each offer or piece of content in your Prime Gaming campaign needs a SKU, or VendorProductId, to identify it across various services. You'll define this value for each offer, enumerate them in a database or similar, and provide the list of SKUs to Prime Gaming to be populated on the Prime Gaming website.
2. Requesting entitlements. While a linked user is playing your game, you'll poll Prime Gaming's Entitlements API at appropriate points (when launching the game, opening an in-game store, etc.) to check for new claims they've made.
3. Content fulfillment. If a player has a new entitlement waiting, you'll match its SKU to the appropriate content in your game and add it to their inventory or account.
4. Fulfillment reporting. Once the player has their new content, you'll call Prime Gaming's Fulfill API to report that it's been successfully delivered. This lets us mark the entitlement as complete, and it will no longer appear in the Entitlements API.

Content Preparation

1. Ensure that the content to be rewarded in your Prime Gaming campaign exists in your game; all art assets, metadata, etc. needed to receive and use the content should be in place for Prime Gaming QA. Please let us know if any content isn't ready to go, or if you require additional time for client updates or first-party reviews.
2. Prepare a list of SKU-type identifiers for each offer and/or item that will be included in your Prime Gaming campaign. In the Prime Gaming Entitlements API, this value is labeled as VendorProductId. Each SKU should be a string and is limited to alphanumeric characters, hyphens (-), underscores (_), colons (:), and periods (.). For example, a SKU might describe the offer itself (e.g. primegaming_season01_drop01) or the offer's content (charactername_specialskin_03).
3. Send the list of SKUs to your Prime Gaming campaign contact. Please let us know right away if you need to change any SKUs after this point.
4. Create or update a database table, static file, or other persistent resource to map each SKU to the item(s) included in that offer. For example, the offer with SKU primegaming_season01_drop01 might map to an add-on with ID abelincoln_skin_mechahat. You'll use this mapping when fulfilling an offer's content to players.

Requesting Entitlements

Request Timing

Pull integrations need to regularly "pull" from the Prime Gaming Entitlements API to ensure that new claims are captured in a timely manner. This doesn't require a WebSocket or constant polling, but should be frequent enough that customers aren't kept waiting and have a clear understanding of how and when they'll get their content. Generally, the goal is to strike a balance between quick fulfillment and a reasonable number of outgoing web requests.

We recommend polling the Entitlements API during big transitional moments and game experiences that players associate with receiving new content. These points will vary based on the nature of your game, but common ones include:

• When the game is launched
• When the game is resumed from standby, sleep, or another inactive state
• When the player navigates to an in-app source of premium items or a paid content store
• When the player enters an inventory of premium items, such as character skins or loot boxes

Prime Gaming entitlement checks should not require an arbitrary player interaction such as a "Check for Rewards" button.

Once you've decided how your game will request entitlements, please provide a short description to your Prime Gaming contact. Players will be shown instructions on how to receive their content in-game after claiming an offer on the Prime Gaming website.

Calling the Entitlements API

This GET request will return a collection of goods to which the current user is entitled. You'll need the user's LWA access token to make the request.

• Endpoint
  GET https://gaming.amazon.com/api/entitlements
• Header (required)
  x-amz-access-token: The current user's LWA access token

An example of a well-formed request:

GET /api/entitlements HTTP/1.1
Host: gaming.amazon.com
Date: Thu, 03 Jun 2022 12:00:00 GMT
x-amz-access-token: Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...

• Returns
  An Entitlements array. Each item in this array has the following parameters:

An example of a successful response:

HTTP/1.1 200 OK
  Content-Type: application/json;charset UTF-8
  Content-Language: en-US
  {
    "Entitlements": [
      {
        "EntitlementId": "b2b5f185-c529-8eee-2b0e-ecd365f74181",
        "NextInstruction": "FULFILL",
        "VendorProductId": "primegaming_season01_drop01"
      }
    ]
  }

Content Fulfillment

To fulfill the content represented by a new entitlement, iterate through the Entitlements array in the Entitlements API response. You should be able to look up a specific content item or bundle for each VendorProductId using the lookup table or mapping you created earlier. After identifying the appropriate content, award it to the player by adding it to their inventory or account as you would any other piece of content.

Additional things to consider during content fulfillment:

• If any of your Prime Gaming offers include unique, non-consumable content that is not exclusive to this campaign (i.e. a player might already have part or all of a given offer's content), you should still fulfill as much as possible. Even if the player is unable to receive any content from the offer because they already have all of it, you should report the entitlement as fulfilled so it will be removed from the Entitlements API.
• Prime Gaming has robust anti-fraud measures, and each offer can only be claimed once per Amazon account. If any of your offers include non-unique, "stackable" rewards like consumables or currency, you need to ensure that each offer can also only be fulfilled once per game account. For more details, see Fraud and Abuse Prevention.

Fulfillment Reporting

This POST request will complete an entitlement's fulfillment by reporting it back to Prime Gaming, which will remove it from future Entitlements API responses.

• Endpoint
  POST https://gaming.amazon.com/api/fulfill
• Header (required)
  Content-Type: application/json
  x-amz-access-token: LWA access token
• Data (JSON format)
  A FulfillmentStatusUpdates array of one or more entitlements to fulfill, each with the following parameters:

An example of a well-formed request:

POST /api/fulfill HTTP/1.1
Host: gaming.amazon.com
Date: Thu, 03 Jun 2022 12:00:00 GMT
Content-Type: application/json;charset UTF-8
x-amz-access-token: Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSR...
{
  "FulfillmentStatusUpdates": [
    {
      "EntitlementId": "b2b5f185-c529-8eee-2b0e-ecd365f74181",
      "LastInstruction": "FULFILL",
      "FulfillmentAddress": "player123"
    }
  ]
}

• Returns
  A FulfillmentStatusUpdates array of fulfillment acknowledgments, each with the following parameters:

An example of a successful response:

HTTP/1.1 200 OK
Content-Type: application/json;charset UTF-8
Content-Language: en-US
{
  "FulfillmentStatusUpdates": [
    {
      "EntitlementId": "b2b5f185-c529-8eee-2b0e-ecd365f74181",
      "Result": "SUCCESS"
    }
  ]
}

Next: What We Need From You