Onboarding · Dashboard Guide
Item Catalogue
Items are the goods your game sells. Adding them to gamemantra's catalogue lets the AI offer pipeline build, price, and serve the right product to the right player at the right moment.
What is an item?
An item is any in-game product that can be offered to a player: a gem pack, a weapon, a cosmetic skin, or an extra life. Items have a category (what type of product), a Value (USD) — computed automatically from your store prices — and a price in cents (what you charge in real money).
The offer pipeline uses your catalogue at every fallback level — from AI-personalized (L1) down to the native store shelf (L4). Without items, the pipeline has nothing to offer and must suppress all offers (L5).
Item categories
Hard currency refills — gems, crystals, diamonds. Used when currency_low fires.
Pipeline role: L2 templates + L4 store shelf
One-time use items — health pots, boosters, extra lives. High urgency.
Pipeline role: L2 templates (first_loss) + L4
Persistent gear — weapons, armor, accessories. Paired with RPG genre events.
Pipeline role: L2 templates (boss_raid) + L3 bundles
Studio-curated packs of multiple items. Managed separately as offer_bundles.
Pipeline role: L3 studio bundles only
Skins, emotes, visual items. Lower conversion urgency — no gameplay impact.
Pipeline role: L3/L4 only when others exhausted
How items flow through the offer pipeline
AI Personalized
ML models (M05/M07) select offer type and price. Items are resolved at build time from the catalogue by category.
Genre Template
offer_templates reference item categories. When boss_raid fires for RPG, the template selects equipment items from your catalogue.
Studio Bundle
offer_bundles specify exact item IDs from your catalogue. These are pre-approved packs you configure.
Native Store Shelf
store_items WHERE fallback_eligible=true. These are pulled as individual items when L1–L3 all return nil.
Silent Suppress
No items available, no offer. The player sees nothing. Better than a wrong offer.
💡 fallback_eligible is the key field
fallback_eligible: true on any item you want to appear in L4 (native store shelf) offers. Items with fallback_eligible: falseare still usable in L3 studio bundles — they just won't be selected automatically.How to add items
Go to Economy → Items in the sidebar, or use the API directly.
Open Economy → Items in the sidebar
Select your game from the top game picker. Click Add Item to open the item form.
Fill in the item details
item_id
Stable identifier used in your game code. Use snake_case. Cannot be changed after creation without a new item. Example: gem_pack_100
category
See the category table above. Determines which genre templates and events can trigger this item.
Value (USD) — computed for you
What this item is worth in USD, derived automatically when you save: currency packs get quantity × the currency's face rate; real-money items get their price. It powers how the offer engine picks "best value" items and how economy charts compare currencies — you don't type it. An edit control exists for the rare expert override.
quantity + image
quantity is the amount the SKU grants ("400 Coins" → 400) — it becomes the offer tile's amount badge. Item art uploads to your asset library and is rendered on offer cards automatically.
price_cents
What you charge in real money, in cents. $0.99 = 99. $4.99 = 499. Used by OPA to enforce the studio's max_price guardrail and Belgium/NL loot box restrictions.
fallback_eligible
Whether this item can appear in L4 (automatic fallback) offers. Enable for anything you'd be happy to show any player automatically. Disable for premium items you want to control manually.
Bulk-add the top 20 items at once
Use Import CSV or the bulk API to add your whole catalogue in one operation. The wizard Step 3 (during game creation) also allows up to 20 items inline.
curl -s -X POST "https://api.gamemantra.ai/v1/games/YOUR_GAME_ID/items/bulk" \
-H "Authorization: Bearer YOUR_DASHBOARD_JWT" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"item_id": "gem_pack_100",
"item_name": "100 Gems",
"category": "currency_pack",
"price_usd": 0.99,
"quantity": 100,
"is_consumable": true,
"fallback_eligible": true
},
{
"item_id": "health_potion",
"item_name": "Health Potion",
"category": "consumable",
"price_usd": 0.49,
"is_consumable": true,
"fallback_eligible": true
}
]
}'No value field needed — each item's Value (USD) is derived on save from its price and quantity.
ON CONFLICT: if an item_id already exists, the API updates its fields. Safe to re-run during CI seed.
Verify items appear in the offer pipeline
After adding items, request a test offer with an empty player feature set. The pipeline should fall to L4 and return items from your catalogue:
# 1. Clear player features (simulates new player with no ML data)
redis-cli DEL "player:features:YOUR_GAME_ID:test_player"
# 2. Register session and request offer
curl -s -X POST https://api.gamemantra.ai/v1/sdk/offers/next \
-H "Authorization: Bearer gm_test_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"session_id":"test-sess","trigger_context":{"event_type":"session_start"}}'
# Expected: fallback_level=4, items array from your catalogue⚠️ Start with currency items for highest impact
Item values are computed for you
Every item's USD value derives from facts you already entered — no formula to learn. The value powers economy health monitoring (FSR, net flow, wallet worth) and the offer engine's "best value" selection.
How it's computed (for the curious)
1. Currency packs — value = quantity × the currency's face rate (the per-unit price of your smallest pack). A discounted big pack's value exceeds its price — that gap IS the "save %" players see.
2. Real-money items — value = the item's price (its real-money price is its USD worth).
3. Items priced in an earned currency — value = in-game price × that currency's derived value.
4. The economy dashboards then compare every currency and item in one unit; healthy FSR ranges stay genre-specific (see Economy docs).
Items connect to LiveOps and Experiments
Items + LiveOps
When a boss_raid live event is active, the pipeline selectsequipment items from your catalogue to fill the offer. Add theme-relevant items before activating a LiveOps event for maximum impact.
Set up LiveOps →Items + Experiments
Experiments can override the price of any offer that includes your items. The variant B config changes price_usd — the items in the offer remain the same, only the price changes. Test one variable at a time.
API quick reference
| Endpoint | What it does |
|---|---|
| GET /v1/games/:id/items | List all items in the catalogue |
| POST /v1/games/:id/items | Add a single item |
| POST /v1/games/:id/items/bulk | Add up to 500 items in one call (ON CONFLICT updates) |
| PATCH /v1/games/:id/items/:item_id | Update an item (price, BCU, description) |
| DELETE /v1/games/:id/items/:item_id | Remove an item (soft delete) |