Quick Start Guide

The Epic Games Store offers an extensive set of ecommerce capabilities that enable you to manage purchasable or redeemable items related to your game, such as downloadable content (DLC) or virtual currency. The system is set up as a hierarchy, so you can optimize bundles within your product offerings. The information below expands upon this system, outlining essential terminology and providing common use cases of how you can use the Ecommerce API to support in-game and back-end functionality.

See the API reference for further guidance to the Ecommerce API.

To help illustrate the Epic Games Store ecommerce capabilities, consider the example configuration below:

Figure 1. Example product ecommerce configuration

In this example, the product (My Game) is configured with 3 sandboxes: Dev, Stage, and Live. Each of these sandboxes has its own ecommerce configuration, consisting of one or more of the following:

• Catalog offers: A catalog offer (also referred to as offer) is a pairing of a catalog item and an associated price (which can be 0). Users can purchase offers in the Epic Games Store. When a user buys an offer, the back-end service grants an entitlement to the user for each of the items contained within the offer.

  • Note: An entitlement is anything a user owns within the Epic Games Store infrastructure. An entitlement can grant access to one or more catalog items.

• Catalog items: A catalog item (also referred to as audience) can represent an entire game, virtual goods like in-game currency or weapon skins, or other types of downloadable content. The service uses catalog items to define how to grant entitlements to users. An entitlement is tied directly to a single catalog item, which in turn may grant ownership rights to additional catalog items.

  • Tip: Catalog items can be configured to grant other catalog items through the Epic Games Store's dynamic bundling feature. Through this feature, you can update associated offers over time, allowing, for example, season pass owners to seamlessly gain ownership rights for new DLC as it is released.

• Library items: A library item (also referred to as game item) is a type of catalog item that the Epic Games Store infrastructure uses to configure additional properties of that catalog item, such as an artifact ID or cloud save configuration. A Library item is always linked to a catalog item.

  • Note Artifacts represent your game's downloadable or playable content such as game clients and DLC. Artifacts are linked to library items. You can configure which binaries are linked to an artifact, determining the content that the Epic Games Launcher downloads and installs. Binaries are uploaded with the BuildPatch Tool.

Catalog offers and catalog items are exposed via the Epic Online Services SDK Ecom Interface (or Web API), which enables you to query all catalog offers and items configured for your product, show in-game checkout flows for catalog offers, as well as query ownership information for catalog items and entitlements.

In our example configuration, we are set up with four offers for our product in the Live sandbox:

• Base game offer: The catalog offer for the base edition of our game. The base game offer is a durable purchase, meaning the player permanently owns it after purchase.This offer consists of a single catalog item, which in turn has a child library item:

  • Base game item: The catalog item for the base edition of our game. This catalog item is used to verify ownership of the base game as described in the use-cases below.
  • Base game library item: The catalog item used to configure the base game artifact, cloud save game configuration, or other game properties.

• Deluxe game offer: The catalog offer for the deluxe edition of our game. This offer is a durable purchase and consists of the following catalog item:

  • Deluxe game item: The catalog item for the deluxe edition of our game that can be used to verify ownership of this edition. The deluxe game item is not linked to a library item of its own and is instead linked to the Base game item (described above) and the DLC item (described below).

• DLC offer: The catalog offer for the DLC of our game; this offer is a durable purchase.

  • DLC item: The catalog item for the DLC of our game. This catalog item is used to verify ownership of the DLC.
  • DLC library item: The catalog item used to configure the DLC artifact or other properties.

• 100 coins offer: The catalog offer for 100 coins of in-game currency. This offer is a consumable purchase, meaning the player can purchase it multiple times and it can be fulfilled in game for a consumable item.

  • 100 coins item: The catalog item for our 100 coins offer. This catalog item is used to retrieve additional information about our offer. However, it is not used to verify ownership, as the offer is a consumable purchase.

Note: Consumable items cannot be granted through purchase of another offer. In other words, if you want the Deluxe game offer to grant players 100 coins as part of the purchase, you will need to incorporate in-game logic that provides the coins to players, as the 100 coins offer will not be displayed in the "Included offers" section of the Deluxe game.

The sections below outline common use cases for how the Ecommerce API can be used to support in-game or back-end functionality.

To display catalog offers in-game for users to purchase, the following flow is used in combination with the Epic Online Services SDK.

1. Authenticate the user using EOS_Auth_Login, as described in the Auth Interface documentation. Typically this is done using the ExchangeCode provided by the Epic Games Launcher, as described here.
2. Use the EOS_Ecom_QueryOffers API, as described in the Ecom Interface documentation, to retrieve a list of available catalog offers. Follow the described pattern to determine the offer count and copy the offers from the SDK cache into your own collection.
   • In our example configuration above, we would retrieve a list of the following offers:
     • Base game offer
     • Deluxe game offer
     • DLC offer
     • 100 coins offer
3. Use the EOS_Ecom_CatalogOffer collection to retrieve offer details, such as the localized title and description, price, and discount information. The offer information will also indicate if the offer is available for purchase, as well as if the current user has already purchased it.

You can now use the information at hand to display offers in-game and present a button to the user to purchase any offers that are available (as determined by the bIsAvailableForPurchases property of EOS_Ecom_CatalogOffer). To use this flow, your game must be configured to use the Epic Online Services Social Overlay.

1. Use the EOS_Ecom_Checkout API, as described in the Ecom Interface documentation, and pass in the catalog offer IDs for each offer the user wishes to purchase.
2. Use the TransactionId returned in the EOS_Ecom_CheckoutCallbackInfo, as described in the Ecom Interface documentation, to determine whether the transaction was successful.

Transactions using the EOS_Ecom_Checkout API can be for either durable or consumable purchases. To learn more, reference the following scenarios to verify the purchases as necessary.

The recommended approach to verify player purchases is from your own back-end service, as this is not susceptible to malicious behavior from users. If you do not have a custom back-end service to implement this verification, refer to the Verify purchased durable content and Verify and fulfill consumable purchases use-cases for client-side verification details.

To perform verification through your back-end service, use one of the following methods that leverage the Ecom Web APIs:

Direct verification refers to directly using an access token to make calls to the Ecom Web APIs from your back-end service.

1. Follow the instructions in the Auth Web APIs documentation to request an access token to use with the Ecom Web APIs.
2. To verify durable purchases, use the Ecom Web APIs API. To verify and redeem consumable purchases, use the entitlement enumeration and redemption APIs.

Token-based verification refers to verifying the authenticity of a JSON Web Token (JWT) generated by the game client, which is then passed to your back-end service. With this method, your back-end service only needs to retrieve a public key once (or until the key is invalidated) to verify multiple tokens generated by the game client.

• For durable content (e.g., DLC): Follow the instructions in the Ecom Interface documentation to generate a JWT in the game client code, using the EOS_Ecom_QueryOwnershipToken API. This JWT can contain ownership information for multiple catalog items.
• For consumable content (e.g. in-game currency): Follow the instructions in the Ecom Interface documentation to generate a JWT in the game client code, using the EOS_Ecom_QueryEntitlementToken API. This JWT can contain entitlement information for multiple entitlements.

After generating a JWT as instructed above, communicate the JWT to your back-end service. Then, decode the token and follow the Ecom Web API documentation to verify that the token is genuine.

The recommended approach to verify player purchases is from your own back-end service, as this is not susceptible to malicious behavior from users. Please refer to the Verify purchases securely using your own back-end service use-case for details.

To verify durable content within your game client, use the EOS_Ecom_QueryOwnership API. This API verifies ownership by passing in a collection of catalog item IDs. This ownership validation automatically takes relationships between catalog items into account.

In our example configuration, a user can purchase the Deluxe game offer or the Base game offer, and both result in a successful validation of the Base game item, as each offer is associated with the Base game item. Similarly, a purchase of the Deluxe game offer results in successful validation of the DLC item, as that catalog item also has a relationship to the Deluxe game offer.

The following flow is used to verify durable content via the EOS_Ecom_QueryOwnership API:

1. Authenticate the user using EOS_Auth_Login, as described in the Auth Interface documentation. Typically this is done using the ExchangeCode provided by the Epic Games Launcher, as described here.

2. Use the EOS_Ecom_QueryOffers API, as described in the Ecom Interface documentation, to retrieve a list of available catalog offers. Follow the described pattern to determine the offer count and copy the offers from the SDK cache into your own collection.

3. Follow the instructions in the Ecom Interface documentation to iterate through the collection of offers to find their associated catalog items (EOS_Ecom_CatalogItem).

   • In our example configuration, we would get the catalog item contained in each catalog offer:
     • Base game offer → Base game item
     • Deluxe game offer → Deluxe game item
     • DLC offer → DLC item
     • 100 coins offer → 100 coins item

   There are two ways you can now verify ownership of these items: directly using the SDK, or by generating a JSON Web Token (JWT) token. These are referenced as the "direct" and "token-based" methods in the Ecom Interface documentation. Below are the steps for the "direct" method, but you can find more information about the "token-based" method under the Verify purchases securely using your own back-end service section of this guide.

4. Use the EOS_Ecom_QueryOwnership API to query for ownership information of a user, using the catalog item IDs. The callback will contain an array of EOS_Ecom_ItemOwnership members for each catalog item ID passed in, with corresponding EOS_Ecom_Owned or EOS_Ecom_NotOwned values.

5. In our example configuration above, if a user has purchased the Deluxe game offer, the Base game item, Deluxe game item, and DLC item will all be marked as EOS_Ecom_Owned.

Consumable purchases can be verified and consumed using the EOS_Ecom_QueryEntitlements and EOS_Ecom_RedeemEntitlements APIs respectively. These APIs verify if a user has purchased an item one or more times and enable tracking of whether any associated consumables in our game have been granted. The EOS_Ecom_QueryEntitlements API takes in EntitlementNames, which are equal to CatalogItem IDs.

In our example configuration, a user can purchase the 100 coins offer one or more times, which results in entitlements that can be redeemed to fulfill these coin offers and add the coins to the player's account.

The EOS_Ecom_QueryEntitlements API should not be used to verify purchased durable content, as it does not take into account the relationship between associated catalog items. As in our example configuration, a user can purchase the Deluxe game offer which consists of both the Base game item and DLC item. In this scenario, the EOS_Ecom_QueryEntitlements API would only return an entitlement for Deluxe game item, ignoring the relationship with the Base game item or DLC item.

1. Authenticate the user using EOS_Auth_Login, as described in the Auth Interface documentation. Typically this is done using the ExchangeCode provided by the Epic Games Launcher, as described here.
2. If you know the entitlement names you want to query for, proceed to step 3. Otherwise follow steps one and two of the Verify purchased durable content (e.g. DLC) use-case above to retrieve the IDs for each applicable catalog item. The catalog item IDs retrieved equal the entitlement names required for this process.
3. Follow the instructions in the Ecom Interface documentation to call EOS_Ecom_QueryEntitlements, which populates the SDK cache with the users entitlements. Then,copy the entitlements from the cache into your own collection.
   • Note: By default, the EOS_Ecom_QueryEntitlements API omits any entitlements that have already been redeemed.
4. Each EOS_Ecom_Entitlement copied from the cache represents a purchase that the user has made and contains a unique EntitlementId. These IDs can be used to fulfill the purchase in your game code.
   • In the example configuration, if a user purchases the 100 coins offer twice, then two separate EOS_Ecom_Entitlement copies will exist for that user, each with a unique EntitlementId.
5. Once an entitlement has been fulfilled in game (e.g., coins have been added to the player account), follow the instructions in the Ecom Interface documentation to mark the entitlement as redeemed in the Ecommerce back-end service using the EOS_Ecom_RedeemEntitlements API.