Inventory

Read a user's owned items, grant items directly (joining rewards, customer support, etc.), or revoke items as a correction. The client-side purchase flow lives under /client/inventory/purchase.

/inventory/revoke is the support / moderation inverse of /inventory/grant — use it to claw back a wrongly-granted item or correct a quantity.

Endpoints

GET /admin/projects/:projectId/inventory/:userId

Response 200

{
  "data": [
    {
      "app_user_id": "…",
      "catalog_item_id": "…",
      "quantity": 3,
      "acquired_via": "grant",
      "acquired_at": "…",
      "catalog_items": { "key": "…", "name": "…", "icon_url": "…", "item_type": "consumable" }
    }
  ]
}

Errors

• 500 FETCH_FAILED.

Try it:

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/inventory/%7B%7BuserId%7D%7D'

Curl:

curl -X GET '${BASE_URL}/admin/projects/{projectId}/inventory/{userId}' \
  -H 'Authorization: Bearer ${DEV_TOKEN}'

POST /admin/projects/:projectId/inventory/grant

Grant an item to a user. If the user already owns it, the quantity is additive. acquired_via is stamped as "grant".

Request (GrantItemInput)

Response 201

{
  "data": {
    "app_user_id": "…",
    "catalog_item_id": "…",
    "quantity": 4,
    "acquired_via": "grant",
    "acquired_at": "…"
  }
}

Errors

• 500 GRANT_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/inventory/grant'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/inventory/grant' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /admin/projects/:projectId/inventory/revoke

The inverse of /grant: decrement the user's held quantity of a catalog item. For support and moderation — claw back a wrongly-granted item or correct a quantity. There is no client-side equivalent; items otherwise only leave an inventory when a consumable is used.

A revoke that zeroes the holding deletes the row entirely, so a subsequent read won't return a phantom zero-quantity item.

Request (RevokeItemInput)

Response 200

When the holding survives, item is the updated inventory row. When the revoke zeroes the holding, the row is deleted and item is null.

{
  "data": {
    "quantity": 2,
    "item": {
      "app_user_id": "…",
      "catalog_item_id": "…",
      "quantity": 2,
      "acquired_via": "grant",
      "acquired_at": "…"
    }
  }
}

Errors

• 400 VALIDATION_ERROR — app_user_id or catalog_item_id missing.
• 400 INVALID_QUANTITY — quantity isn't a positive integer.
• 400 INVALID_ID — app_user_id or catalog_item_id isn't a UUID.
• 400 INSUFFICIENT_QUANTITY — the user holds fewer than quantity. The message includes both the held and requested amounts; no partial revoke.
• 404 INVENTORY_ITEM_NOT_FOUND — the user doesn't hold this item at all.
• 500 REVOKE_FAILED.

Try it:

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/inventory/revoke'

Curl:

curl -X POST '${BASE_URL}/admin/projects/{projectId}/inventory/revoke' \
  -H 'Authorization: Bearer ${DEV_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{
        "app_user_id": "…",
        "catalog_item_id": "…",
        "quantity": 1
      }'