Shops and Inventory

Flock’s economy has three pieces:

Shops — collections of purchasable items.
Shop items — individual offers with a price and currency.
Inventory — a record of what each player has purchased.

Scope: shops and items are defined per game version; inventory is per player.

A purchase debits the player’s wallet and records an inventory entry:

Shop item ──purchase──▶ wallet debit ──▶ inventory entry

Every purchase creates its own entry, so buying the same item twice gives you two. Each entry carries a server-set status (unused, used, or revoked after a refund) and used_at. Using an item, which the SDKs call consuming it, marks its entry used. A purchase is never charged twice, and never queued offline. Inventory is always fetched fresh; the catalog is cached and served offline, so treat a displayed price as advisory until the purchase succeeds. Items can also cost real money, paid through the App Store or Google Play on a phone: see In-App Purchases. On Windows, macOS, Linux and WebGL they are paid through a web checkout: see Web Payments.

The id a purchase takes

A purchase names a shop item by its id: the id of the item inside its shop. It is not the item’s name, and it is not the shop’s id. Read it from the shop rather than typing it in: the SDK lists the shops of the Game Version your build runs, each with its items. Unreal’s generated shop items carry the id already. A shop belongs to one Game Version, so a shop made under another version is not listed and cannot be found by name. If the list comes back empty, check the dashboard shows the shop under the Game Version your build runs.

A wallet is made when the player registers. The server builds each player’s wallet from the Game Version’s currency template at registration, with every currency starting at zero. Create the currency template before your test player registers; a player who registered before it existed has no wallet to pay from. A player whose wallet was made under another Game Version keeps it: at sign-in the server moves it to this version’s currency template, balances kept and new currencies at zero. See Currencies and Wallets.

When a call fails, the SDK’s text says what is wrong and how to fix it. A purchase given the item’s name instead of its id reads:

Shop item with ID 'GoldItem' not found [shop_item.shop_item_not_found, HTTP 404]
Fix: ... take the shop item's Id ..., not the item's name or the shop's id.

A request.not_found 404 whose reason is a bare Not Found means the request reached no route at all (any other reason names a record the route did not find): the API URL must be the Flock server’s address alone, with no /v1 or other path after it.

Purchases grant their contents server-side. Give a shop item a type of Currency pack or Consumable and attach rewards to it, and the server credits the player as part of the same transaction that debits the price. Neither half can happen without the other, and the client never decides what was granted — so a modified client cannot award itself anything, and a dropped connection cannot leave a player charged with nothing to show for it.A Standard item is the older behaviour and still the default: it debits the price and records an inventory entry your game interprets however it likes. The wallet sells a standard item again on every purchase, so before offering one, check the player does not hold it already. (A store sells it only once: see In-App Purchases.)

Dashboard
Unity
Unreal

An item is priced in a currency, so first create the currency config of this Game Version (see Currencies and Wallets). Without one, the shop’s items say Add a currency config to enable item creation, with Go to Currencies.

In the menu at the top of the page, choose your game and the Game Version your build runs. A shop belongs to that one version.
Open Monetization → Shops. Under Your Shops, press New.
Type the Shop Name, leave Status at Active, and press Create Shop. Success: the page says Shop created. Add your first item. and the shop is listed under Your Shops.
With the shop selected, open its Items tab and press Add Item.
In New Item, fill in:
- Item Name, and Status (Active to sell it).
- Item type, which decides what the player gets:
  - Standard adds an entry to the player’s inventory and grants nothing more; your game decides what it means. A wallet sells it again on every purchase.
  - Currency pack pays its rewards straight into the player’s wallet when bought, with no inventory entry.
  - Consumable sits unused in the player’s inventory and pays its rewards when your game consumes it.
- Price and Currency. In a game currency the price is a whole number, such as 50. In a real currency, type it as the player sees it, such as 4.99: the server keeps it in the currency’s smallest unit, so the SDK reads 499.
- Store product IDs (App Store, Google Play): only for an item sold inside a mobile app (see In-App Purchases).
- Rewards, for a currency pack or a consumable: press Add reward, pick a currency other than the price’s, and enter a whole Amount above zero. A pack needs a second currency in the currency config.
Press Add Item. Success: the item shows in Shop Items with its price and currency, its rewards, and Real money when a real currency prices it.

Preview as player shows the shop as a player sees it. A version deployed to Production is locked: its shops and items are read-only there and change only through a patch.

The Shops page with two shops under Your Shops and the selected shop's items — Monetization → Shops: a shop's Items tab, with Add Item.

One call buys any item: Shop.PurchaseAsync(item.Id). An item priced in a game currency is paid from the wallet; a real-money item goes through the store (see In-App Purchases). Every example below is the signed-in player’s and runs inside an async method; "Main Shop" stands for your shop’s name.The player needs a wallet to pay from. A test player made in the Quickstart before your currency template existed has none: call FlockClient.Instance.Authentication.Logout() once, then delete the device ID the SDK keeps (the file Flock/device_id.txt under Application.persistentDataPath) or pass a new device ID of your own, such as Guid.NewGuid().ToString(), and press Play again to register a new player. Then give it currency with AddGameFundsAsync; Currencies and Wallets has both steps in full.Show the shop. Read the items, the wallet and what the player owns once, then draw each item.

using System.Collections.Generic;
using Flock;
using Flock.Models;

// The shop item's id from its shop: not the item's name, and not the shop's id.
Shop shop = await FlockClient.Instance.Shop.GetByNameAsync("Main Shop");
FlockWallet wallet = await FlockClient.Instance.Player.GetWalletAsync();
IReadOnlyDictionary<string, int> owned = await FlockClient.Instance.Shop.GetOwnedItemCountsAsync();

foreach (ShopItem item in shop.ShopItems)
{
    owned.TryGetValue(item.Id, out int count);
    string price = $"{item.Price} {item.Currency}";                       // e.g. "20 Gold"
    bool canPay = item.IsRealMoney || wallet.CanAfford(item);              // grey out what the wallet cannot pay for
    bool alreadyHeld = item.Type == ShopItemTypes.Standard && count > 0;  // the wallet would sell it again
}

In the examples below, item, potion and sword are ShopItems read from the shop as above.Buy an item. The answer says what was granted and the wallet afterwards.

using Flock;
using Flock.Models;
using UnityEngine;

PurchaseResult bought = await FlockClient.Instance.Shop.PurchaseAsync(item.Id);

foreach (ShopItemReward reward in bought.Granted)
    Debug.Log($"+{reward.Amount} {reward.Code}");           // e.g. +500 Gold
long gold = bought.Balances?.BalanceOf("Gold") ?? 0;       // null when no currency moved
PlayerInventory entry = bought.Inventory;                  // null for a currency pack

When the purchase does not go through. A purchase that buys nothing throws. Three cases cover a shop screen:

using Flock;
using Flock.Exceptions;
using UnityEngine;

try
{
    await FlockClient.Instance.Shop.PurchaseAsync(item.Id);
}
catch (FlockException e) when (e.ErrorCode == FlockErrorCode.ShopInsufficientFunds)
{
    // Not enough of the item's currency: nothing was bought. Tell the player.
}
catch (FlockException e) when (e.OutcomeUnknown)
{
    // No answer said whether it went through, so it may have. Read the wallet and
    // the inventory again before offering it again.
}
catch (FlockException e)
{
    Debug.LogWarning(e.Message);   // what went wrong, then a "Fix:" line saying how to fix it
}

A purchase whose answer never came (a dropped connection, a timeout, a server error) is sent again by itself, under one key the server uses to answer a repeat with the first purchase, so the player pays once. A new PurchaseAsync call is a new purchase. OutcomeUnknown is true when no answer said whether it went through.Use a consumable. ConsumeOneAsync uses one of a shop item the player holds and grants what it holds.

using Flock;
using Flock.Exceptions;
using Flock.Models;
using UnityEngine;

try
{
    ConsumeResult used = await FlockClient.Instance.Shop.ConsumeOneAsync(potion.Id);
    foreach (ShopItemReward reward in used.Granted)
        Debug.Log($"+{reward.Amount} {reward.Code}");
}
catch (FlockValidationException)
{
    // The player holds none (it may have been used on another device).
}
catch (FlockException e) when (e.OutcomeUnknown)
{
    // No answer came, so it may have been used: read the inventory again.
}

Using an item is never sent twice by itself. To use one particular entry, pass its id: ConsumeAsync(entry.Id).Does the player own it?

using Flock;

bool hasSword = await FlockClient.Instance.Shop.OwnsAsync(sword.Id);   // an unused entry of the item

With generated code. After Sync Schemas (the Code Generation tab of Flock → Settings), every item has a typed id in FlockShopItemId, named after the item. These names exist only once you have synced, and only for the items of your own shops: GoldPack, Potion and Sword here are examples.

using Flock;
using Flock.Generated.Shops;

await FlockClient.Instance.Shop.PurchaseAsync(FlockShopItemId.GoldPack);
await FlockClient.Instance.Shop.ConsumeOneAsync(FlockShopItemId.Potion);
bool hasSword = await FlockClient.Instance.Shop.OwnsAsync(FlockShopItemId.Sword.ShopItemId());

A purchase or a use that reports a wallet also writes it into the cached player data, so the next wallet read shows the new balance. To show what an item will give before the player buys it, read ShopItem.Rewards; Granted and Rewards are never null.

Code	What happened	What to do
`ShopInsufficientFunds`	The player cannot afford the item	Read the wallet before offering it
`ShopCurrencyNotHeld`	The wallet has no balance in the item’s currency	Price it in a currency of the wallet’s template
`ShopWalletNotFound`	The player has no wallet in this Game Version	Create the currency template, then register the player
`ShopItemShopItemNotFound`	No item has that id	Pass `ShopItem.Id` from its shop
`ShopItemNotForSale`	The item, or its shop, is set to Inactive in the dashboard	Read the shop again, which leaves it out; set it back to Active to sell it
`PlayerInventoryAlreadyUsed`	That entry was used already	Read the inventory again

Browse with the Flock | Shop nodes, or the shop provider in C++. An item’s free-form data and stats read by dotted path, so no JSON parsing node is needed.Purchase completes with everything the purchase produced — what was granted, the wallet afterwards, and the inventory entry if the item created one.An item priced in a game currency is paid from the player’s wallet at once. An item priced in a currency your currency config lists as real money (for the Game Version the game sends) goes through the store the game connected with UFlockStore::Connect (Flock Connect Store in Blueprint): the phone’s store (see In-App Purchases), or a web checkout on Windows, macOS and Linux (see Web Payments). With no store connected, it is refused and nothing is charged.

A Flock Purchase node in a Blueprint graph — Purchase by picking a generated item — the ID is baked in and cannot be mistyped.

Read the shop. In C++, read the shop item’s id from its shop: Purchase takes FFlockShopItem::Id, not the item’s name and not the shop’s id.

#include "FlockSubsystem.h"
#include "Providers/FlockPlayerProvider.h"
#include "Providers/FlockShopProvider.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

Sdk->GetShopProvider()->GetByName(TEXT("Main Shop"),
    [](TFlockResult<FFlockShop> Shop)
    {
        for (const FFlockShopItem& Item : Shop.Value.ShopItems)
        {
            // Item.Id is what Purchase takes; Item.Name is for showing the player.
        }
    });

Flock Get Shop By Name into Break Flock Shop, whose Shop Items drive a ForEach Loop into Break Flock Shop Item — Read a shop by its name and walk its items: each item's Id is what Flock Purchase takes.

Show the shop. Read the wallet and what the player holds once, then decide per item. The wallet comes from the player-data cache, which purchases keep current; the inventory is read from the server on every call, so read the counts once for a whole screen.

// Items: the shop items the screen shows, read from their shop as above.
const TWeakObjectPtr<UFlockSubsystem> Flock = Sdk;
Sdk->GetPlayerProvider()->GetWallet([Flock, Items](TFlockResult<FFlockWallet> Wallet)
{
    if (!Wallet.bSuccess || !Flock.IsValid())
    {
        return;
    }
    Flock->GetShopProvider()->GetOwnedItemCounts([Balances = Wallet.Value, Items](TFlockResult<FFlockOwnedItemCounts> Owned)
    {
        if (!Owned.bSuccess)
        {
            return;
        }
        for (const FFlockShopItem& Item : Items)
        {
            const int32 Held = Owned.Value.CountOf(Item.Id);   // unused entries the player holds
            const bool bCanBuy = Balances.CanAfford(Item);       // false for a real-money item
            // The wallet sells a standard item again on every purchase: offer it only while Held is 0.
        }
    });
});

Buy.

// ItemId: the Id of an item read from its shop, as above.
Sdk->GetShopProvider()->Purchase(ItemId,
    [](TFlockResult<FFlockPurchaseResult> Bought)
    {
        if (!Bought.bSuccess)
        {
            if (Bought.Error.ErrorCode == EFlockErrorCode::ShopInsufficientFunds)
            {
                // The server declined — show the player, don't retry.
            }
            else if (Bought.Error.bOutcomeUnknown)
            {
                // No answer said whether it was bought: read the wallet and inventory before offering it again.
            }
            // What went wrong, then a "Fix:" line saying how to fix it.
            UE_LOG(LogTemp, Warning, TEXT("%s"), *Bought.Error.ToDisplayText());
            return;
        }

        for (const FFlockShopItemReward& Reward : Bought.Value.Granted)
        {
            // e.g. +500 GOLD. Ask the reward, never compare Type to a typed-out "currency":
            // the server owns that set and can add kinds.
            if (Reward.IsCurrency()) { /* Reward.Code, Reward.Amount */ }
        }

        // Both may legitimately be absent, so ask rather than testing the Id yourself.
        if (Bought.Value.HasWallet())       { /* Bought.Value.Wallet — balances after the grant */ }
        if (Bought.Value.HasInventoryRow()) { /* Bought.Value.Inventory — the row the player owns */ }
    });

A currency pack pays straight into the wallet and creates no inventory entry — HasInventoryRow() is false, which is the legitimate no-row case rather than an error. A Consumable does the opposite: it lands in the inventory and grants when the player spends it.

// InventoryId: an entry's Id from GetPlayerInventory.
Sdk->GetShopProvider()->Consume(InventoryId,
    [](TFlockResult<FFlockConsumeResult> Consumed)
    {
        for (const FFlockShopItemReward& Reward : Consumed.Value.Granted) { /* +Amount Code */ }
    });

// Or use up one entry of a shop item the player holds, without reading the inventory yourself.
Sdk->GetShopProvider()->ConsumeOne(PotionItemId,
    [](TFlockResult<FFlockConsumeResult> Used) { /* Used.Value.Granted */ });

// Whether the player holds one: a standard item bought and not used up.
Sdk->GetShopProvider()->Owns(PotionItemId, [](TFlockResult<bool> Holds) { /* Holds.Value */ });

PotionItemId is a shop item’s Id. ConsumeOne reads the inventory and uses the first unused entry of that item, passing over one used meanwhile on another device; any other failure stops it, so one call never uses two. It fails (Validation) when the player holds none. Owns reads the whole inventory. With nobody signed in, ConsumeOne fails (Auth) and Owns fails (Validation, saying to sign in first). Consume is not refused by the SDK: it is sent as it is, so call it only while a player is signed in.In Blueprint these are Flock Purchase, Flock Consume Inventory Item, Flock Consume One, Flock Owns Shop Item and Flock Get Owned Item Counts. For a shop screen, read the wallet with Flock Get Wallet (under Flock | Player) and the owned counts once, then ask per item Can Afford (wallet, item) and Owned Count Of (counts, item id). Break the purchase result for Inventory, Granted and Wallet, and use the nodes that have no execution pins rather than testing fields yourself: Has Inventory Row before reading the row, and Is Currency Reward to branch on a reward kind. Comparing a reward’s Type to a hand-typed string is the one mistake worth guarding against — a typo reads as “not a currency reward” and silently skips the grant. A purchase or consume that reports a wallet also writes it into the cached player data.Granted is never null — an item that grants nothing returns an empty list. To show what an item will give before the player buys it, read Rewards from the catalog item.A declined purchase fails the result rather than throwing — check Error.ErrorCode for EFlockErrorCode::ShopInsufficientFunds to tell “can’t afford it” apart from a network failure.A purchase is never bought twice. Every attempt of one Purchase call carries the same key, so an answer that never came is sent again and the server answers the repeat with the first purchase. A second Purchase call is a second purchase. When no answer said whether it went through, the failure has bOutcomeUnknown set (Outcome Unknown on the Blueprint error): read the wallet and inventory before offering the item again. That is for an item paid from the wallet; a real-money item whose outcome is unknown is handled as In-App Purchases says. A consume is never sent again after an ambiguous failure, since it carries no key and a repeat would grant twice; it reports bOutcomeUnknown the same way.

See Currencies and Wallets for the balances that back purchases.

Getting Started

Concepts

Features

Reference

Shops and Inventory

The id a purchase takes

​The id a purchase takes

The id a purchase takes