Ecom Interface Overview

Implement interface for handling purchases and verification of ownership

Epic Games Store
19 mins to read

The Ecom Interface gives developers using Epic Online Services (EOS) the ability to support in-game purchases through the Epic Games Store (EGS). With this interface, you can manage products ranging from full games and downloadable content (DLC) to virtual goods and in-game currency. This includes making offers, completing purchase transactions, verifying ownership, and redeeming purchased items.

See the Ecom Web APIs documentation for using Web APIs with the Ecom Interface.

To access the Ecom Interface, acquire an EOS_HEcom handle through the Platform Interface function, EOS_Platform_GetEcomInterface. All Ecom Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking in order for callbacks to trigger when requests are completed.

To use the Ecom Interface, your product must have Epic Account Services (EAS) active, and must obtain player/user consent to access Basic Profile data. You can activate EAS on the Developer Portal, or learn more in Epic's documentation. Without EAS and player consent, you will still be able to initialize the EOS SDK and the Ecom Interface, but all Ecom Interface function calls to the back-end service will fail.

Operating an In-Game Store

An in-game store under EOS operates by carrying out two functions: presenting Catalog Offers (sometimes called "Offers") from the store to the player for purchase, and enabling the player to make purchases. The EOS SDK provides functionality to retrieve lists of offers from the store's catalog for display in whatever way the game developer desires. Offer data includes one or more items that the player will gain, as well as key images and release details that you can use to present information about the offer to the player.

Once the player chooses to make a purchase, the checkout process pushes the data to the EGS Overlay, which finalizes the purchasing process. EOS will then notify the game of the result of the transaction, providing a transaction handle so that the game can carry out fulfillment in the event that the purchase was completed successfully.

Purchase related functionality of the Ecom interface is disabled if the EOS_PF_DISABLE_OVERLAY flag is set.

Catalog Offer Data

Catalog Offers (type EOS_Ecom_CatalogOffer) contain localized pricing information and descriptive text, based on the player browsing the store. Price localization includes applying discounts and converting to the local currency. A localized price will include a currency code, such as "USD" (to represent US dollars), and is represented in the smallest possible unit of that currency. For example, an Offer that costs 2.99 US dollars would correspond to the value 299.

Presenting the Store's Catalog

You can retrieve the list of Catalog Offers defined in the Developer Portal by calling the EOS_Ecom_QueryOffers function. This function takes an EOS_Ecom_QueryOffersOptions data structure and will call your delegate, of type EOS_Ecom_QueryOffersCallbackInfo, upon completion. Initialize your EOS_Ecom_QueryOffersOptions structure as follows:

PropertyValue
ApiVersionEOS_ECOM_QUERYOFFERS_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the local player who is requesting the query
OverrideCatalogNamespaceOptional product namespace, if not the one specified during initialization

If the ResultCode in the EOS_Ecom_QueryOffersCallbackInfo that the delegate receives indicates success, the Offer data you requested is available in a temporary cache. Use EOS_Ecom_GetOfferCount to determine the number of Offers stored in the cache, and EOS_Ecom_CopyOfferByIndex to get a copy of an individual Offer (of type EOS_Ecom_CatalogOffer) from it. Each Item within the Offer contains data about images and release details associated with that Item, which you can pull out separately. When you no longer need your copy of an Offer, use EOS_Ecom_CatalogOffer_Release to release it.

Displaying Individual Item Data

After retrieving an Offer from the cache, you can call EOS_Ecom_GetOfferItemCount to determine how many Items that Offer includes, and then use EOS_Ecom_CopyOfferItemByIndex to retrieve a copy of an individual EOS_Ecom_CatalogItem. This structure contains additional localized text as well as the ID of the Entitlement that it will provide upon purchase. To release the memory allocated to your copy of the data, call EOS_Ecom_CatalogItem_Release.

Images associated with Items are also available in the cache; you can call EOS_Ecom_GetItemImageInfoCount to determine how many images are associated with a given Item, and then use EOS_Ecom_CopyItemImageInfoByIndex to obtain an EOS_Ecom_KeyImageInfo for the image's URL, dimensions, and intended usage. When you no longer need your copy of this data, use EOS_Ecom_KeyImageInfo_Release to free the memory it used.

To retrieve release details for an Item from the cache, first use EOS_Ecom_GetItemReleaseCount to discover the number of data entries present. You can then use EOS_Ecom_CopyItemReleaseByIndex to get an individual piece of data (of type EOS_Ecom_CatalogRelease). Call EOS_Ecom_CatalogRelease_Release to release this data when you no longer need it.

Buying from the Store

When a player buys something from the store, that player is accepting a Catalog Offer. Once the purchase is complete, the player will own the Item (or Items) contained within the Offer, each of which adds one or more Entitlements to the buyer's player account.

There are three actions involved in buying from the store: Making the purchase, verifying ownership, and (optionally) redeeming Entitlements.

When a player decides to make a purchase, call EOS_Ecom_Checkout with an EOS_Ecom_CheckoutOptions structure. Initialize the structure as follows:

PropertyValue
ApiVersionEOS_ECOM_CHECKOUT_API_LATEST
LocalUserIdThe EOS_EpicAccountId of the local player who is making the purchase
OverrideCatalogNamespaceIf not provided, the current SandboxId will be supplied as the catalog namespace.
EntryCountThe number of EOS_EcomCheckoutEntry elements being supplied to this structure in the Entries parameter.
EntriesAn array of EOS_Ecom_CheckoutEntry elements, which contain the EOS_Ecom_CatalogOfferId data for each Offer the player wishes to purchase, and the same ApiVersion as this structure

After making this call, EOS will use this information to generate a purchase token. EOS will then use this purchase token to open its own overlay, enabling the player to review the purchase, select payment options, and confirm or cancel the transaction. When the overlay closes, whether by succeeding, failing, or being canceled by the player, your callback (of type EOS_Ecom_OnCheckoutCallback) will run with an EOS_Ecom_CheckoutCallbackInfo parameter detailing the transaction. Within the callback information, the TransactionId will be non-null if the transaction succeeded, and null if it failed or was canceled.

If any additional calls to EOS_Ecom_Checkout are made before the first returns via the callback then it will give an EOS_AlreadyPending error.

Accessing Completed Purchase Data

If you have a valid transaction ID following a successful player purchase, you can pass it to the EOS_Ecom_CopyTransactionById function to receive an EOS_Ecom_HTransaction. EOS_Ecom_Transaction_GetEntitlementsCount returns the number of Entitlements associated with the transaction, and EOS_Ecom_Transaction_CopyEntitlementByIndex will retrieve an individual Entitlement. Call EOS_Ecom_Entitlement_Release to release this data when you no longer need it.

Entitlements associated with transaction IDs contain the same data as those obtained through the EOS_Ecom_QueryEntitlement function, but are subject to a different caching policy. Because of this difference, Entitlements that you acquire using a transaction ID following a purchase will remain in a transaction-specific cache until you explicitly call EOS_Ecom_Transaction_Release.

Verifying Ownership

Verifying ownership within the game client is not recommended and may be bypassed by players using software cheats. If possible, verify ownership on a trusted server using the Ecom Web APIs.

Latest recommendations to assist with preventing piracy