Create a Fulfillment API

Overview

In a Prime Gaming push integration, you create and maintain a fulfillment API. When a customer claims an offer for your title's campaign on the Prime Gaming website, an entitlement for that offer's content will be generated and sent to this API. Your web services are then responsible for identifying the game content granted by the specified SKU and awarding it to the player, fulfilling the entitlement.

The following is a high-level overview of the fulfillment process in a push integration, 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 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. API authentication. Your fulfillment API will be publicly accessible, so it needs suitable security to prevent unauthorized access.
3. API design and content fulfillment. You'll configure your API to accept incoming fulfillment requests, match the entitlement's SKU to the appropriate content in your game, and award it to the appropriate player's inventory or account.

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 identifiers for each offer and/or item that will be included in your Prime Gaming campaign. 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.

Fulfillment API Authentication

Since your fulfillment API will be public, it needs to enforce authentication. We currently support the two models outlined below.

API Key

API Key Authentication relies on the endpoint owner to generate and register a string value in their backend systems. You can think of this API key as a static access token or password that is included in every fulfillment call to establish caller identity. Please note that because API keys are static, a leaked key can significantly impact your endpoint's security.

To use this model, configure your fulfillment API to require a bearer-type Authorization header as seen below. Your Prime Gaming tech contact will work with you on a secure way to deliver your API key.

Authorization: Bearer <API key>

OAuth Client Credential Flow

OAuth Client Credential Authentication uses a client ID and client secret to generate an access token that is attached to every fulfillment request. This authentication method follows the standard OAuth 2.0 Client Credential Exchange flow. If you've already implemented LWA account linking for your push integration, this process will be familiar to you:

1. Prime Gaming stores a client ID and client secret generated by your authorization server.
2. Prime Gaming exchanges the client ID and secret with your server for a short-lived access token.
3. Prime Gaming uses the access token as an authorization header when calling your fulfillment API.

To use this model, your server must be capable of generating client IDs and client secrets and provide an OAuth 2.0-compliant access token exchange API. Please provide your Prime Gaming contact with a client ID and client secret (or a web portal where they can be generated), along with the URL of your access token exchange API.

Fulfillment API Specification

Prime Gaming's push fulfillment services send requests to many different endpoints, so we ask that all partners design their fulfillment APIs to the same specification (also known as an API schema). The Prime Gaming fulfillment API schema is detailed below.

Request Schema

POST: <your fulfillment endpoint>
Host: <your host>
Content-Type: application/json
Authorization: Bearer "<API key or access token>"
{
    "account_id": "...",
    "sku": "...",
    "transaction_id": "..."
}

Response Schema

HTTP 2XX: "Success"
{}

HTTP 4XX: (Non-Retryable except for 429)
{
    "error": {
        "code": "<error code>",
        "message": "<error message>"
    }
}

HTTP 5XX: (Retryable)
{}

Prime Gaming logs all error responses regardless of content, but providing a code and message for 5xx responses will help with debugging.

Content Fulfillment

To fulfill requests sent to the fulfillment API, extract the account_id and sku values. The account_id should map to an account in your system, and the sku should map to a specific content item or bundle. After identifying the content and the customer's account, deliver it to them 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.
• 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.

Next: What We Need From You