Last Updated: 4/25/2022, 9:58:59 AM

# Catalog

# Overview

Catalog services cover Store Management allow you to manage your store, put games, in-game items, or add-ons up for sale, and sort these items into categories. Catalog Management includes several features, such as:

  • Item localization lets you display different names and descriptions of your items for sale in different countries.
  • Item regional data allows items to have different currencies and prices for sale in different countries.
  • Item bundling allows you to sell items in groups for a lower price than if those items were purchased separately.
  • Store isolation allows for only one store to be published online at any time, but you can make as many draft stores as you like. If you want to make changes to your store, you can ensure those changes work as intended in your draft store before putting it online, to reduce the chance of errors occurring.
  • Store Cloning lets you create an exact copy of your store in its environment, for easy editing.
  • Store Import/Export lets you import a store from or export a store to a different environment as a JSON file. If your store is working well in your dev environment, you can export it as a JSON file and import it to your production environment without having to recreate it.
  • Image and Item Tags can be created and assigned to images or items to determine where those objects will appear. For example, you can create a banner tag and define where banner images are displayed, and every banner image will behave the same way on its own page. Item tags are used to select which games or items for sale are featured on the main page of your store. Up to six objects can be featured.
  • Purchase limitations enable you to limit how many times a player can purchase a particular item.

# Permissions

Permissions are used to grant access to specific resources within our services. Make sure your account has the following permissions before you attempt to manage the catalog in the Admin Portal. For a full list of permissions that impact catalog management, see the Platform/Commerce tab of the permissions reference.

Usage Resource Action
Create a Store ADMIN:NAMESPACE:{namespace}:STORE Create
Create a Category ADMIN:NAMESPACE:{namespace}:CATEGORY Create
Create a KeyGroup ADMIN:NAMESPACE:{namespace}:KEYGROUP Create
Create an Item in Store ADMIN:NAMESPACE:{namespace}:ITEM Create

Permissions work slightly differently depending on whether they are assigned to IAM Clients or Roles assigned to users. For more information, read the Authentication and Authorization documentation.

# Managing Catalog in the Admin Portal

# Create a Store

  1. In the Admin Portal, go to the Commerce section and click the Stores menu.

    catalog

  2. On the Stores page, go to the Draft Store section and click the Create Draft Store button.

    NOTE

    You can only have one draft store.

    catalog

  3. Input the required information into the form below.

    catalog

    • Input your store Title. The store title will be visible in the Launcher and Player Portal as your store name.
    • Select the Default Language.
    • Select the Default Region.
    • Select the Other Languages supported besides the default language, if desired.
    • Select the Other Regions supported besides the default region, if desired.
    • Input a Description for your store.
  4. When you’re done, click Create.

  5. The draft store appears on the Stores page. The next thing you need to do is add item categories and items to your store.

    catalog

# Create a Category

  1. In the Draft Store, click the more button under the Action column and choose View to add categories.

    catalog

  2. In your Store, click the Create button, and the Create Category form will be displayed.

    catalog

  3. Input the fields with the appropriate format.

    catalog

    • You can add more paths to create sub-categories. For example, /items/game-items.
    • Input the category name based on other languages and regions that have been registered.
    • Here is an example of categories you can use:
    • /games for games in your store.
    • /coins for virtual currency.
    • /items for all in-game items. You can also separate in-game categories for every game in the store using /items/gameappId.
  4. When you’re done, the new category will be added to the list.

    catalog

  5. Note that the changes you made inside the store will not appear in the Player Portal until the store is published.

# Create a KeyGroup

Creating a KeyGroup is useful if you need to add a Product Key that can be redeemed on the desired platform.

  1. Go to Platform Configurations in the Admin Portal and click Product Keys.

    catalog

  2. On the Product Key page, click the Add Key Group.

    catalog

  3. Fill in the required fields.

    • Input the Key Group Name.
    • Input a Description of the KeyGroup.
    • Upload your Key file with the appropriate format.

    catalog

  4. When you’re done, the new KeyGroup will be added to the list.

    catalog

# Create an Item in a Store

  1. In your store page, go to the Items tab. Click the Create Items button and choose whether you wanted to create a new item or clone from another namespace. In this case, we will choose to Create a New Item.

    catalog

  2. Input the Item Name and choose the Item Type from the list.

    catalog

    Here’s how to add an item of each type:

    1. Add a Game
    2. catalog

      • Select Game as the App Type.
      • Input the App ID with a unique combination of alphanumeric characters. The App ID is a unique identifier that will be used to identify your game when you upload it using BuildUtil

      Note that you can not change the App ID after it has been defined.

    3. Add a Coin
    4. catalog

      • Select Coin as the Item Type.
      • Select the currency code for the coin from the Coin Currency Code dropdown list.

    5. Add an In-Game Item
    6. Before creating In-Game Items, make sure you already have a game registered in your store.

      catalog

      • Input the Required Game.
      • Select the desired game namespace for the Target Namespace.
      • Choose the Entitlement Type. If you want the item to be able to be used repeatedly, choose Durable. If your item is single-use, choose Consumable.
      • Follow these additional steps for Consumable items:
        • Input Use Count to define how many times the item can be used.
        • Set the Stack Entitlement value. Set to True if the item should be stackable. If not, set to False.

    7. Add a Bundle
    8. catalog

      • Select Bundle from the App Type list.
      • Select the game your bundle is associated with from the Required Game (optional) list.

    9. Add a Code
    10. catalog

      • Select Code as the App Type.
      • Select the KeyGroup from the dropdown list. Make sure you’ve already created a KeyGroup.

    11. Add a Subscription Item
    12. catalog

      • Select how often subscribing players will be billed in the Billing Cycle field. You can choose to charge the user either Weekly, Monthly, Quarterly, or Yearly.
      • Input the desired Grace Period to give players extra time to pay, in case of payment processing issues. The default setting is 7 days.
      • Input the price of the subscription in the Price field.

      The rest of the settings will depend on whether or not you want to offer a trial subscription, and whether or not that trial will be free.

      No Trial, Paid Trial, and Free Trial Terms

      No Trial

      • If you choose not to offer a trial, make sure that the Free option under Trial Period is disabled.
      • Do not make a selection in the Length dropdown menu under Trial Period.
      • Leave the Trial Price field blank.

      Paid Trial

      • To offer a paid trial, make sure that the Free option under Trial Period is disabled.
      • Select how long you would like the trial to last in the Length dropdown menu under Trial Period.
      • Input the price of the trial in the Trial Price field. The trial price is usually lower than the normal price.

      Free Trial

      • To offer a free trial, enable the Free option under Trial Period.
      • Select how long you would like the trial to last in the Length dropdown menu under Trial Period.
      • With the Free option enabled, the Trial Price field will not appear.

    13. Add a Media Item
    14. catalog

      • Select Media as the Item Type.

    15. Add a Pass or Tier Item
    16. For more information, see the Season Pass documentation.

      TIP

      It’s highly recommended to create any pass or tier items in a draft store, so that you don’t have to take your store offline every time you wish to edit them. Pass and tier items do not have to be available in your published store in order for them to be usable in season events.

      catalog

      • Select Season for the Item Type.
      • Select the Item:
        • Choose Pass to create a pass item that allows players to participate in seasonal events. Passes can be made free or available for player purchase.
        • Choose Tier to create a tier item that grants players access to rewards. You can give players the option to purchase tiers to access rewards they have not earned through participation in season events.

      Once completed, fill in the remaining required fields.

      catalog

  3. Choose if you want to make your item Visible in Store. Select True to make the item visible, or select False to hide the item from your published store.

  4. Choose if you want to make the item Purchasable in Store. Select True to make your item available for purchase, or False to make it unavailable for purchase.

    How to Use Visible in Store and Purchasable in Store
    • Use the Visible in Store and Purchasable in Store settings for items that you want to be immediately available to players.
    • Use the Visible in Store but Non-Purchasable in Store settings if you want to preview to players items that will be available at a later time.
    • Select False for Visible in Store and Purchasable in Store to save items as drafts which can be worked on later before being published to the store.
  5. Select the Category of the item you are creating. The categories you created earlier will appear in the dropdown list.

  6. Input the item’s ID from the Third Party Platform that supports In-App Purchases into the SKU No. if you want to map this item to a Third Party Platform. Below is a list of Third Party Platforms that support In-App Purchases, and which values you need to enter into the SKU No. field:

    Third Party Platforms that support In-App Purchases
    Third Party Platform Value
    PSN Entitlement Label
    Xbox StoreID
    Twitch Reward ID
    Google productId
    Apple productId
    Stadia product_id
    Epic productId
  7. If your in-game item is available in a Third Party Store such as Playstation, Xbox, or Epic Games, select 3rd Party Store Integration. This option is only used for Coins, In-Game Items, and Bundles.

  8. Set the Purchase Limit to define the purchase limit for every account. For example, if you set the Purchase Limit of an item to 100, this means that 100 units of that particular item will be available for purchase in your store. To make this value unlimited, input -1.

  9. For Coins, In-Game Items, and Bundles, define the Purchase Limit per Account. For example, if you set the limit to 100, this means that a player can purchase that particular item up to 100 times. To make this value unlimited, input -1.

  10. For consumable items such as Coins and other In-Game Items, input the Use Count to determine how many times the item can be used by a player.

  11. Use the Display Order field to set where the item is displayed in the Player Portal. This field is optional.

Once you have completed the above steps,fill the Default Region Data.

catalog

  1. Select your publisher namespace from the Currency Namespace dropdown menu.

  2. Select the Currency Code for your store from the list.

  3. Input the Price of the item. If you want to make an item free, set the price as 0. When you set a price in real currency, set last two digits as decimals, i.e., if you have selected $ as your current symbol, 1.99 will set your item as $1.99 in your store.

    catalog

  4. Once completed, click Add and your item will be added your store’s Item list.

# Add Items to a Bundle

After you’ve created a bundle, you can add items to the bundle by following the steps below.

  1. In the Admin Portal, go to your draft store and find the bundle you want to add items to. Open the bundle by clicking View in the bundle’s Action menu.

    catalog

  2. Here you can see detailed information about the bundle. Scroll down to the Bundle Items to see the list of items contained within that bundle. To add more items or edit them, click the Add/Edit Item button.

    catalog

  3. The Add/Edit Item form appears. Select the items you want to add to the bundle.

    catalog

    • Select the item type of the item you want to add from the Type dropdown menu. The item types that can be added to bundles are In-Game Item, Coins, App from the publisher namespace only, and Season Pass and Season Tier in game namespaces only.
    • Select the item you want to add to the bundle from the Item dropdown menu. You can type the name of the item in the box to select it.
    • Enter the quantity of the item you want to add in the Quantity column. You can add multiples of in-game items or coin packs to a bundle, but you cannot add more than one of an App, Season Pass, or Season Tier item.
    • To add more items click Add More Item, then fill out the fields for the new item as seen above.

    catalog

    When you’re done, click the Save button.

  4. The items you added will appear in the Bundle Items section.

    catalog

# Add a Regional Price to an Item

By default, your item’s price is set in the default country for your store. To add different prices for different regions, follow the steps below:

  1. In the Admin Portal, go to your item details. In the Pricing panel, click Add New to add new pricing.

    catalog

  2. Input the following information into the Add Price window that appears:

    • Select the Region where you want to set the regional price. If you can’t find the desired region, you can edit the store to add the region to it.
    • Select the publisher namespace as the Currency Namespace.
    • Select the Currency Code from the list.
    • Input the Price of the item. If you are making a free item, set the price to 0. When you set a price for real currency, the last two digits are decimals.
    • If you want to set when the item will be available on the store, you can input the Available From field to make the item available from the desired date and time. Otherwise, the item will appear as soon as the store is published. You can also set when the item will be removed from the store on the Expiry Date field. If left empty, the item will never expire.
    • Set the Discount price if you want to give your item a discount. You can choose to add a discount by an amount or by a percentage.
    • You can also set the Discount Release Date and Discount Expire Date. Like the Available From and Expiry Date fields, these fields determine when your discount begins and ends.

    catalog

  3. When you’re finished, click the Add button and the price will be updated.

    catalog

# Setting Up the Publishing Content

Publishing content consists of the information and media used to show and describe your items, such as the item descriptions, images, and information about system specifications and requirements.

  1. Go to the Publishing Content section. In the Localization section, click the View button to add a description of the item. You can input both a Short Description and Long Description. Each of the descriptions has their own function as you can see in the image below.

    catalog

  2. To add description in other languages, go back to the Localization section and click the Add button.

    catalog

  3. The Add Language Data form appears and you need to fill in the required fields.

    catalog

    • Select the Language of the description from the drop-down list
    • Input the Title of the content
    • Input the Short Description of the content
    • Input the Long Description of the content. This is optional.
  4. The description you added will appear on the product’s detail page in the Player Portal when you select the relevant language.

    catalog

# Configure Images in the Admin Portal

  1. In the Publishing Content panel, select the Image tab.

    catalog

  2. Click the Upload button, then select the image you want to upload from your local directory. After the image is selected, you can use the image as you desire. For example, if you want to set the image as a product banner, you can fill the Set As field with product-banner.

    catalog

  3. See the table below for information about image setup in the Admin Portal. You can also configure images in Contentful.

    UI/UX Module

    Location

    Tags

    Set Image as

    Tags

    Behavior

    Set Image as

    Behavior

    Recommended Image Size

    Hero Banner

    [Player Portal] Home Page- Slider Carousel

    banner

    Any product with Banner tags will be shown as the Product Banner and Hero Banner

    hero-banner

    Note: The image for the hero banner can also be set from Contentful

    16:6 ratio with recommended width: 1920px

    Featured Item Thumbnail

    [Player Portal] Home Page- Product under the carousel

    featured

    Any product with the Featured tag will be shown on Featured Games

    product-cover

    The image will be used as the product thumbnail

    4:3 ratio with recommended width: 800px

    Game Icon

    Launcher - Sidebar

    n/a

    n/a

    game-icon

    The image will be used as the icon for the game in Launcher

    1:1 ratio with recommended resolution: 256 x 256px

    Game Logo

    Launcher- Game Logo

    n/a

    n/a

    game-logo

    The image will be used as the logo for the game in Launcher

    Recommended width 180px

    Game Download Cover

    Launcher - Game Download Pop Up Box

    n/a

    n/a

    game-download-cover

    The image will appear when the player is downloading the game in Launcher

    300 x 100px

    Other

         

    unset

    This is an error that occurs when the image is unable to be saved. If this occurs, try to upload your image again.

     
  4. You can add as many images as you need. When you’re done adding an image it will appear in the Publishing Content window, as seen below:

    catalog

    Here is an example of a hero banner in the Player Portal:

    catalog

# Add Product Information

  1. In the Publishing Content panel, select the Product Information tab.

  2. Fill out the Product Information fields:

    catalog

    • Input the Primary Genre of your game.
    • Input any additional genres in the Genre field, if desired. You can input more than one genre.
    • Choose the Platforms supported by your game.
    • Input the Release Date of your game.
    • Input the Developer of your game.
    • Input the Publisher of your game.
    • Input the Website URL.
    • Input the Forum URL.

    Here’s an example of product information listed in the Player Portal.

    catalog

# Add System Requirements

  1. In the Publishing Content panel, select the System Requirement tab.

    catalog

  2. Fill out the Minimum Requirement fields.
    catalog

    • Input the minimum supported OS Version.
    • Input the minimum supported Processor.
    • Input the minimum supported amount of RAM.
    • Input the minimum support Graphics card.
    • Input the supported DirectX Version.
    • Input the minimum required amount of Disk Space.
    • Input the minimum supported Sound Card.
  3. Fill out the Recommended Requirement fields.
    catalog

    • Input the recommended OS Version.
    • Input the recommended Processor.
    • Input the recommended amount of RAM.
    • Input the recommended Graphics card.
    • Input the recommended DirectX Version.
    • Input the recommended amount of Disk Space.
    • Input the recommended Sound Card.

    catalog

  4. Here is an example of system requirements in the Player Portal.

    catalog

# Manage Subscription Contents

# Add Subscription Content

You can add your games to the subscription plan by following the steps below. Make sure you’ve created a subscription plan and added a game to your store.

  1. In the Admin Portal, go to your newly created Subscription Item and switch to the Subscription Contents tab. Then, click the Add New button to add an Item to the Subscription.

    catalog

  2. A modal appears. Here you can select the Item you want to add.

    catalog

    When you’re done, click Add and the item will be added to the subscription content list.

  3. You can also remove an item from the subscription plan, but be aware that this will make current players lose access to the item.

    catalog

# Add Item into Subscription Plan

Besides adding items in the Subscription Content, you can also add a game into Subscription Plan via item details. Make sure you have created a subscription item.

  1. Choose the game from your store and click View to open the item details.

    catalog

  2. Go to Include in the Subscription Content section and click the Add to Subscription button.

    catalog

  3. A pop-up appears and you need to choose the subscription plan where you want to add the game to.

    catalog

    Once you’ve done, click Add and the game will be added to the chosen subscription plan.

# Recent Changes

To see your recent changes, open the Admin Portal, go to your draft store, and open the Recent Changes tab. In this tab, you can see all the changes made in your draft store before publishing. Every time your draft store is published, the changes list will be wiped, and then refreshed if any subsequent changes are made.

catalog

You can filter the Recent Changes list by:

  • Action: list changes by All actions, or by Create, Update, or Delete actions.
  • Type: list changes by All types, or by Store, Category, or Item.
  • Date: the date filter can be set to a maximum range of one month.

catalog

# Publish a Store

  1. Select the Store you want to publish. Click the Action field then choose Publish.

    catalog

  2. Confirm that you are ready to publish your store by typing “PUBLISH” in the field. Your store is now published.

    catalog

  3. After you publish the draft store, the draft store will still exist as a draft. This will allow you to make further changes later without affecting the published store.

    catalog

# Clone a Store

  1. Select the Store you want to clone. In the Action column, click Clone to Draft and a form will appear.

    catalog

  2. A form will appear and you need to select the Target Store from the list, then click Clone. The target store will receive the cloned data from the source store.

    catalog

    Here you can see the Target Store has been cloned to Draft Stores.

    catalog

# Export and Import a Store

As an administrator, you can also import or export a store to or from the Admin Portal, to be used by another administrator. Before you import a store, make sure you’ve performed the following actions:

  • Make sure a target store exists. If it doesn’t yet, you can create a new one.
  • Make sure the default language and region between the imported store and the target store are the same.

# Export a Store

  1. In the Admin Portal, select the Store you want to export. Click the Action field then choose Export from the dropdown menu.

    catalog

  2. The store will be exported as a ZIP file, which when extracted will produce a JSON file containing your store data.

# Import a Store

  1. In the Admin Portal, select the Store you want to import store data into. Click the Action field then choose Import from the dropdown menu.

    catalog

  2. The Import Store modal appears. Click the Browse button to search for the store data you want to import.

    catalog

  3. Select which store you want to upload from the directory. After the store has been uploaded, click the Import button.

    catalog

  4. The target store now contains the imported data.

    catalog

# Implementing Catalog using SDK

# Store Category

The store category is useful to organize items in your store catalog into groups. The category APIs can be called by using the functions on AccelByte::FRegistry::Category.

# Retrieve Store Root Categories

Retrieve root or top most level categories.

# Retrieve Store Category

Retrieve information on a specified category.

# Retrieve Store Child Categories

Retrieve a list of subcategories that is one level below a specified category.

# Retrieve Store Descendant Categories

Retrieve a list of subcategories that are multiple levels below a specified category.

# In-Game Item

The Item APIs can be called by using the functions on AccelByte::FRegistry::Item and the APIs can be used to get an item from specific Id, get items that match some criterias, search items with specific keywords.

# Get Item Info

Get an item information from the published store by specifying itemId parameter.

# Query Item by Criteria

Get a list of items from the published store that match specific criterias/filters. Available criterias are like the following:

  • ItemType: Allow enumeration values from the enum class EAccelByteItemType. There are 5 item types available which are: COINS, INGAMEITEM, BUNDLE, APP, CODE.
  • AppType: Allow enumeration values from the enum class EAccelByteAppType. There are 5 item types available which are: GAME, SOFTWARE, DLC, DEMO.
  • Region: Define item region. Using current store region settings when unspecified.
  • Language: Define item language. Using current store language settings when unspecified.
  • CategoryPath: An item category path. Example: “/equipment/weapon”.
  • SortBy: Allow string values. There are 11 sorting types available which are: name, name:asc, name:desc, createdAt, createdAt:asc, createdAt:desc, updatedAt, updatedAt:asc,updatedAt:desc, displayOrder, displayOrder:asc, displayOrder:desc.
  • Tags: Define item tags.

# Search Items

Search items from the published store by using keywords in the title, description, and long description. The function is language constrained, which requires a language code to properly function. If items don’t exist in the specified region, default region items will be returned. When offset and limit value is less than 0, the default value will be used which are 0 for offset and 20 for limit

# Connecting Custom Services to Catalog using the Server SDK

# SDK Initialization

Before using the Store (opens new window) service from the SDK, you will need to initialize your server-side SDK to ensure you are authorized and able to perform create, read, update, and delete actions.

# Golang SDK Initialization

Before using the Store service from the Golang SDK, you will need to initialize the SDK by following the steps below:

storeService := &platform.StoreService{
    Client:          factory.NewPlatformClient(&repository.ConfigRepositoryImpl{}),
    TokenRepository: &repository.TokenRepositoryImpl{},
}

Once completed, you can use the Golang SDK to create, read, update, or delete Stores (opens new window) from your serverless app.

# Python SDK Initialization

Before using the Store service from the Python SDK, you will need to initialize the SDK by following the steps below:

Once completed, you can use the Python SDK to create, read, update, or delete Stores (opens new window) from your serverless app.

# .NET (C#) SDK Initialization

Before using the Platform service, you will need to set some permissions. Use the following .NET namespaces:

using AccelByte.Sdk.Api.Platform.Model;
using AccelByte.Sdk.Api.Platform.Operation;
using AccelByte.Sdk.Api.Platform.Wrapper;

# Java SDK Initialization

Before using the Platform service, you will need to set some permissions. Initialize the Store wrapper from the Platform service using the following code:

Store wStore = new Store(sdk);

Once completed, you can use the SDK to create, read, update, or delete stores.

# Create a Store

Use the following function to create a store (opens new window):

# Delete a Store

Use the following function to delete a store (opens new window):

# Retrieve a Store

Use the following function to retrieve a store (opens new window):

# Update a Store

Use the following function to update a store (opens new window):

  • Read about Orders to see how players can use your store once you’ve set it up.
  • If you’re interested in running a promotional code redemption, check out our Code Redemption page.
  • See more information about the Rewards to see how the players can get the rewards that the item is from your store since you are already set up.
  • In addition to publishing your own catalog, you can also integrate our services with catalogs on 3rd party platforms. Check out our In-App Purchase Integration guide to learn more.