Item Catalog

The item catalog defines all purchasable items in your app. Items can be durable (owned forever), consumable (used up), or bundles (contain other items).

Item types

MCP tools

Example: Set up an item catalog

Agent: "Create a theme shop with gold pricing"

amba_catalog_items_create({
  project_id: "proj_xxx",
  key: "theme_dark",
  name: "Dark Theme",
  description: "A sleek dark theme for your app",
  category: "themes",
  item_type: "durable"
})

amba_catalog_items_set_price({
  project_id: "proj_xxx",
  catalog_item_id: "item_xxx",
  currency_code: "gold",
  price: 200
})

amba_catalog_items_create({
  project_id: "proj_xxx",
  key: "extra_life",
  name: "Extra Life",
  category: "powerups",
  item_type: "consumable"
})

Client API reference

Purchase an item

POST /v1/client/inventory/purchase
 
{ "catalog_item_id": "<item id or key>", "currency_code": "gold" }

catalog_item_id takes the item's id or its key (sku and currency_key are accepted as aliases). currency_code can be left out when the item has a price in one currency only; an item priced in several answers 400 CURRENCY_REQUIRED. Pass store_id to buy at a store listing's price. An item that an active store limits per user (max_purchases_per_user) is sold through that store only: without store_id it answers 409 STORE_PURCHASE_REQUIRED. A purchase answers:

{ "data": { "purchased": true, "currency_code": "gold", "price": 200, "balance_after": 300 } }

A single-item purchase also returns the inventory row it added to (id, sku, quantity and the rest of an inventory item). await Amba.inventory.purchase({ sku: 'theme_dark', currency_key: 'gold' }) sends this request and resolves with data, typed InventoryPurchase. The bought item (or a bundle's contents) is now in the user's inventory; Amba.inventory.getItems() lists it. A purchase buys one item: to buy several, call purchase once per item. A request with a quantity other than 1 answers 400 QUANTITY_NOT_SUPPORTED and charges nothing. Add store_id to buy through a store's listing, at its price and within its per-user limit; see Stores.