> For the complete documentation index, see [llms.txt](https://wiki.tribute.tg/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.tribute.tg/for-content-creators/api-documentation/products.md).
# Products
Product operations. Products exist in three types:
* `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments
* `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings
* `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts
All amounts are in smallest currency units (cents/kopecks)
## Get Products List
> Returns a paginated list of products
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"Product ID"},"type":{"type":"string","description":"Product type","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"amount":{"type":"integer","format":"int64","description":"Product price in smallest currency units (cents for USD/EUR, kopecks for RUB). For physical products this is the starting price, taken from the cheapest variant."},"currency":{"type":"string","description":"Currency code","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Price in Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Whether payment with Stars is enabled"},"status":{"type":"string","description":"Product status","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Whether this is a custom product"},"acceptCards":{"type":"boolean","description":"Whether card payments are accepted"},"acceptWalletPay":{"type":"boolean","description":"Whether wallet payments are accepted"},"protectContent":{"type":"boolean","description":"Whether content protection is enabled"},"created":{"type":"string","format":"date-time","description":"Product creation date"},"updated":{"type":"string","format":"date-time","description":"Product last update date"},"pendingOrders":{"type":"integer","description":"Number of pending orders (for custom products)"},"imageUrl":{"type":"string","format":"uri","description":"Product image URL"},"link":{"type":"string","format":"uri","description":"Direct link to product in Telegram app"},"webLink":{"type":"string","format":"uri","description":"Web link to product"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products":{"get":{"summary":"Get Products List","description":"Returns a paginated list of products","tags":["Products"],"parameters":[{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","description":"Filter by product type","required":false,"schema":{"type":"string","enum":["digital","custom","physical"]}},{"name":"desc","in":"query","description":"Sort by ID descending","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Total number of items"},"offset":{"type":"integer","format":"int64","description":"Current page number"},"limit":{"type":"integer","format":"int64","description":"Page size"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Product by ID
> Returns a single product by its ID
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"Product ID"},"type":{"type":"string","description":"Product type","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"amount":{"type":"integer","format":"int64","description":"Product price in smallest currency units (cents for USD/EUR, kopecks for RUB). For physical products this is the starting price, taken from the cheapest variant."},"currency":{"type":"string","description":"Currency code","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Price in Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Whether payment with Stars is enabled"},"status":{"type":"string","description":"Product status","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Whether this is a custom product"},"acceptCards":{"type":"boolean","description":"Whether card payments are accepted"},"acceptWalletPay":{"type":"boolean","description":"Whether wallet payments are accepted"},"protectContent":{"type":"boolean","description":"Whether content protection is enabled"},"created":{"type":"string","format":"date-time","description":"Product creation date"},"updated":{"type":"string","format":"date-time","description":"Product last update date"},"pendingOrders":{"type":"integer","description":"Number of pending orders (for custom products)"},"imageUrl":{"type":"string","format":"uri","description":"Product image URL"},"link":{"type":"string","format":"uri","description":"Direct link to product in Telegram app"},"webLink":{"type":"string","format":"uri","description":"Web link to product"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products/{id}":{"get":{"summary":"Get Product by ID","description":"Returns a single product by its ID","tags":["Products"],"parameters":[{"name":"id","in":"path","description":"Product ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad request (invalid product ID format)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Cancel Digital Product Purchase
> Cancels a digital product purchase and refunds the payment.\
> \
> \*\*Important:\*\* This endpoint only supports refunds for purchases paid with Telegram Stars.\
> Purchases paid with other payment methods cannot be refunded via this endpoint.
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products/purchases/{purchaseId}/cancel":{"post":{"summary":"Cancel Digital Product Purchase","description":"Cancels a digital product purchase and refunds the payment.\n\n**Important:** This endpoint only supports refunds for purchases paid with Telegram Stars.\nPurchases paid with other payment methods cannot be refunded via this endpoint.\n","tags":["Products"],"parameters":[{"name":"purchaseId","in":"path","description":"Digital product purchase ID (ProductPurchase.ID)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Purchase successfully cancelled and payment refunded","content":{"application/json":{"schema":{"type":"object","required":["success","purchaseId","message"],"properties":{"success":{"type":"boolean","description":"Operation success status"},"purchaseId":{"type":"integer","description":"Cancelled purchase ID"},"message":{"type":"string","description":"Success message"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied (not the product owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Purchase or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://wiki.tribute.tg/for-content-creators/api-documentation/products.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.