# Shop
Shop and purchasing APIs. Used to retrieve purchasable items, process purchases, and ensure atomic settlement between item ownership and wallet balance.
## Get shop items of the game
> Returns list of shop items available in the game.\
> Game context is resolved from \`x-api-key\`.
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Server SDK)","version":"1.0.0"},"tags":[{"name":"Shop","description":"Shop and purchasing APIs.\nUsed to retrieve purchasable items, process purchases,\nand ensure atomic settlement between item ownership\nand wallet balance.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Production Environment"},{"url":"https://sandbox.api.sverse.io","description":"Sandbox / Testing Environment"}],"paths":{"/api/private/shop-items":{"get":{"tags":["Shop"],"summary":"Get shop items of the game","description":"Returns list of shop items available in the game.\nGame context is resolved from `x-api-key`.\n","parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}},{"name":"purchasable","in":"query","description":"Filter items that can be purchased","schema":{"type":"boolean"}},{"name":"currency","in":"query","description":"Filter by currency code","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort field","schema":{"type":"string","enum":["createdAt","price"]}},{"name":"order","in":"query","description":"Sort order","schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","description":"Page number","schema":{"type":"integer","minimum":1,"default":1}},{"name":"limit","in":"query","description":"Number of items per page","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Get shop items successfully","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"item_def_id":{"type":"string"},"price":{"type":"number"},"currency_code":{"type":"string"},"purchasable":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Invalid API key","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```
## Purchase a shop item
> Purchase a shop item for a user.\
> This endpoint performs an atomic operation:\
> \- check balance\
> \- debit wallet\
> \- grant item\
> Supports idempotency.
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Server SDK)","version":"1.0.0"},"tags":[{"name":"Shop","description":"Shop and purchasing APIs.\nUsed to retrieve purchasable items, process purchases,\nand ensure atomic settlement between item ownership\nand wallet balance.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Production Environment"},{"url":"https://sandbox.api.sverse.io","description":"Sandbox / Testing Environment"}],"paths":{"/api/private/users/{identity}/purchases":{"post":{"tags":["Shop"],"summary":"Purchase a shop item","description":"Purchase a shop item for a user.\nThis endpoint performs an atomic operation:\n- check balance\n- debit wallet\n- grant item\nSupports idempotency.\n","parameters":[{"name":"identity","in":"path","required":true,"description":"User identity","schema":{"type":"string"}},{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["shopItemId","quantity","idempotencyKey"],"properties":{"shopItemId":{"type":"string","description":"Shop item ID"},"quantity":{"type":"integer","minimum":1},"idempotencyKey":{"type":"string","description":"Unique key to prevent duplicate purchases"},"meta":{"type":"object","description":"Additional metadata"}}}}}},"responses":{"200":{"description":"Purchase successful","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"type":"object","properties":{"purchaseId":{"type":"string"},"user":{"type":"string"},"item":{"type":"object","properties":{"shopItemId":{"type":"string"},"itemDefId":{"type":"string"},"quantity":{"type":"integer"}}},"cost":{"type":"object","properties":{"currency":{"type":"string"},"amount":{"type":"number"}}},"wallet":{"type":"object","properties":{"balanceBefore":{"type":"number"},"balanceAfter":{"type":"number"}}}}}}}}}},"400":{"description":"Invalid request or insufficient balance","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"404":{"description":"User or shop item not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}},"409":{"description":"Duplicate request (idempotency hit)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"data":{"description":"Previously processed purchase result","type":"object"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://sverse-1.gitbook.io/sverse-docs/api-reference/server/shop.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.