# Shop
Shop APIs. Used by client applications to list purchasable items and perform purchase operations directly via Sverse.
## Get shop items
> Retrieve list of shop items available in the game shop.\
> \
> This API supports filtering, sorting, and pagination.\
> Typically used by game clients to display purchasable items.\
> \
> Example:\
> \`/api/public/shop-items?filter\[purchasable]=true\&sort=createdAt\&order=desc\&page=1\&limit=10\`
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Client SDK)","version":"1.0.0"},"tags":[{"name":"Shop","description":"Shop APIs.\nUsed by client applications to list purchasable items\nand perform purchase operations directly via Sverse.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Sverse Managed Backend (Production)"}],"paths":{"/api/public/shop-items":{"get":{"tags":["Shop"],"summary":"Get shop items","description":"Retrieve list of shop items available in the game shop.\n\nThis API supports filtering, sorting, and pagination.\nTypically used by game clients to display purchasable items.\n\nExample:\n `/api/public/shop-items?filter[purchasable]=true&sort=createdAt&order=desc&page=1&limit=10`\n","parameters":[{"name":"filter[purchasable]","in":"query","required":false,"description":"Filter items that can be purchased.","schema":{"type":"boolean"}},{"name":"sort","in":"query","required":false,"description":"Field used for sorting.","schema":{"type":"string"}},{"name":"order","in":"query","required":false,"description":"Sort order.","schema":{"type":"string","enum":["asc","desc"]}},{"name":"page","in":"query","required":false,"description":"Page number.","schema":{"type":"integer","minimum":1}},{"name":"limit","in":"query","required":false,"description":"Number of items per page.","schema":{"type":"integer","minimum":1}}],"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"},"itemDefId":{"type":"string","description":"Item definition identifier."},"price":{"type":"number"},"currency":{"type":"string"},"purchasable":{"type":"boolean"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"totalPages":{"type":"integer"}}}}}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"boolean"},"message":{"type":"string"}}}}}}}}}}}
```
## Purchase shop item
> Purchase a shop item for the currently authenticated user.\
> \
> This API deducts the required currency from the user's wallet\
> and grants the purchased item to the user.\
> \
> \### Authentication\
> \- \*\*Bearer Token\*\*: \`sessionId\` returned from Login API\
> \- \*\*x-api-key\*\*: Required\
> \
> This API is intended for \*\*developers without their own backend\*\*.
```json
{"openapi":"3.0.3","info":{"title":"Sverse Managed Backend (Client SDK)","version":"1.0.0"},"tags":[{"name":"Shop","description":"Shop APIs.\nUsed by client applications to list purchasable items\nand perform purchase operations directly via Sverse.\n"}],"servers":[{"url":"https://be.sverse.io","description":"Sverse Managed Backend (Production)"}],"security":[{"sessionAuth":[]}],"components":{"securitySchemes":{"sessionAuth":{"type":"http","scheme":"bearer","bearerFormat":"sessionId","description":"Use the `sessionId` returned from the Login API.\nExample:\nAuthorization: Bearer 9d7b6121-30d3-44cf-8b4f-c00e2f4f016e\n"}},"schemas":{"ErrorResponse":{"type":"object","required":["error","code","message"],"properties":{"error":{"type":"boolean"},"message":{"type":"string","description":"Human-readable error message (dynamic)"},"details":{"type":"object","description":"Optional additional error details","additionalProperties":true},"requestId":{"type":"string","description":"Unique request identifier for tracing"}}}}},"paths":{"/api/public/items/purchases":{"post":{"tags":["Shop"],"summary":"Purchase shop item","description":"Purchase a shop item for the currently authenticated user.\n\nThis API deducts the required currency from the user's wallet\nand grants the purchased item to the user.\n\n### Authentication\n- **Bearer Token**: `sessionId` returned from Login API\n- **x-api-key**: Required\n\nThis API is intended for **developers without their own backend**.\n","operationId":"purchaseItem","parameters":[{"name":"x-api-key","in":"header","required":true,"schema":{"type":"string"},"description":"API key provided for your game"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["itemId","quantity"],"properties":{"itemId":{"type":"string","description":"Shop item identifier"},"quantity":{"type":"integer","minimum":1},"meta":{"type":"object","description":"Optional metadata from client","additionalProperties":true}}}}}},"responses":{"200":{"description":"Purchase successful","content":{"application/json":{"schema":{"type":"object","required":["error","data"],"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":"integer"}}},"wallet":{"type":"object","properties":{"balanceBefore":{"type":"integer"},"balanceAfter":{"type":"integer"}}}}}}}}}},"400":{"description":"Invalid request or insufficient balance","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Shop item not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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/client/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.