# Methods
Shop methods for managing orders and recurring payments.
### Payment Methods
Available payment methods depend on the order configuration:
**Standard orders** (`onlyStars: false`):
| Method | Availability |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Bank cards | Always available |
| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: "onetime"`) |
| Wallet Pay (TON) | Always available |
| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |
**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):
| Method | Availability |
| -------------- | ------------------------------------------------------ |
| Telegram Stars | Always available |
| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |
> **Note:** Pix and PayPal are **not available** for shop orders.
## Get Shop
> Returns shop information for the authenticated user
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"/shop":{"get":{"summary":"Get Shop","description":"Returns shop information for the authenticated user","tags":["Methods"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["id","userId","name","link","callbackUrl","recurrent","onlyStars","status"],"properties":{"id":{"type":"integer","format":"uint64","description":"Shop ID"},"userId":{"type":"integer","description":"Shop owner user ID"},"name":{"type":"string","description":"Shop name"},"link":{"type":"string","description":"Shop link/slug"},"callbackUrl":{"type":"string","format":"uri","description":"Webhook callback URL for order notifications"},"recurrent":{"type":"boolean","description":"Whether recurring payments are available"},"onlyStars":{"type":"boolean","description":"Whether only Telegram Stars payment is accepted"},"tokenCharging":{"type":"boolean","description":"Whether merchant-initiated token charging is enabled"},"status":{"type":"integer","description":"Shop status (0 = inactive, 1 = active)","enum":[0,1]}}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop Orders
> Returns a list of shop orders sorted by ID descending (newest first). Optionally filter by date range.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"ShopOrder":{"type":"object","required":["uuid","shopId","amount","currency","title","description","status","successUrl","failUrl","paymentUrl","createdAt","period"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID this order belongs to"},"amount":{"type":"integer","format":"int64","description":"Order amount in smallest currency units (cents/kopecks)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"title":{"type":"string","description":"Order title (max 100 UTF-16 characters)"},"description":{"type":"string","description":"Order description (max 300 UTF-16 characters)"},"status":{"type":"string","description":"Order status","enum":["pending","paid","failed"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"successUrl":{"type":"string","format":"uri","description":"Redirect URL on successful payment"},"failUrl":{"type":"string","format":"uri","description":"Redirect URL on failed payment"},"paymentUrl":{"type":"string","format":"uri","nullable":true,"description":"Web URL for customer to complete payment in a browser.\n`null` for OnlyStars orders — they can only be paid inside Telegram via `webappPaymentUrl`.\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment"},"createdAt":{"type":"string","format":"date-time","description":"Order creation timestamp in ISO 8601 format"},"comment":{"type":"string","description":"Optional comment for the order"},"period":{"type":"string","description":"Billing period for recurring orders","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"memberStatus":{"type":"string","description":"Recurring subscription status (only for recurring orders)","enum":["active","cancelled"]},"memberExpiresAt":{"type":"string","format":"date-time","description":"Recurring subscription expiration date in ISO 8601 format (only for recurring orders)"},"lastPaidTransactionAt":{"type":"string","format":"date-time","nullable":true,"description":"Date of the last paid transaction in ISO 8601 format. Null if no transactions exist."},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars (0 if not set)"},"onlyStars":{"type":"boolean","description":"Whether this order only accepts Telegram Stars payment"},"image":{"type":"object","nullable":true,"description":"Order image displayed in Telegram Stars invoices and transactions. Null if no image is set.","properties":{"id":{"type":"integer","description":"Image ID"},"path":{"type":"string","format":"uri","description":"Image URL"},"thumbnail":{"type":"string","description":"Base64-encoded thumbnail"},"width":{"type":"integer","description":"Image width in pixels"},"height":{"type":"integer","description":"Image height in pixels"},"fileType":{"type":"string","description":"File type","enum":["image","video"]}}}}},"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":{"/shop/orders":{"get":{"summary":"Get Shop Orders","description":"Returns a list of shop orders sorted by ID descending (newest first). Optionally filter by date range.","tags":["Methods"],"parameters":[{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (inclusive) in UTC, format yyyy-mm-dd"},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (inclusive) in UTC, format yyyy-mm-dd"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/ShopOrder"}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create Shop Order
> Creates a new shop order and returns a payment URL for the customer. Supports one-time and recurring payments.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"/shop/orders":{"post":{"summary":"Create Shop Order","description":"Creates a new shop order and returns a payment URL for the customer. Supports one-time and recurring payments.","tags":["Methods"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","currency","title","description"],"properties":{"shopId":{"type":"integer","format":"uint64","description":"Shop ID to create the order for. If omitted, the order is created for the first (oldest) shop of the authenticated user."},"amount":{"type":"integer","format":"int64","description":"Order amount in smallest currency units (cents for EUR/USD, kopecks for RUB)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"title":{"type":"string","description":"Order title (required, max 100 UTF-16 characters)"},"description":{"type":"string","description":"Order description (required, max 300 UTF-16 characters)"},"successUrl":{"type":"string","format":"uri","description":"Redirect URL on successful payment (optional, must be valid URL)"},"failUrl":{"type":"string","format":"uri","description":"Redirect URL on failed payment (optional, must be valid URL)"},"email":{"type":"string","format":"email","description":"Customer email (optional, validated if provided)"},"comment":{"type":"string","description":"Optional comment for the order"},"customerId":{"type":"string","description":"Unique customer identifier","maxLength":256},"period":{"type":"string","description":"Billing period. Defaults to \"onetime\" if not specified. Recurring periods require shop.recurrent to be enabled. OnlyStars shops only support \"onetime\" and \"monthly\" periods (Telegram Stars subscriptions are 30-day cycles).","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"],"default":"onetime"},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars. Required for OnlyStars shops. When set, enables Stars payment as an option. Only supported for `onetime` or `monthly` periods. For monthly orders, creates a Telegram Stars subscription.","minimum":1},"imageUrl":{"type":"string","format":"uri","description":"Image URL for the order. Will be displayed in Telegram Stars invoices and transactions. If provided, the image is downloaded and stored; if an image with this URL already exists, it is reused."}}}}}},"responses":{"200":{"description":"Order created successfully","content":{"application/json":{"schema":{"type":"object","required":["uuid","shopId","paymentUrl","webappPaymentUrl"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID the order was created for"},"paymentUrl":{"type":"string","format":"uri","nullable":true,"description":"Web payment URL for customer to complete payment in a browser.\n`null` for OnlyStars orders — they can only be paid inside Telegram via `webappPaymentUrl`.\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment"}}}}}},"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 (shopId belongs to another user)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop Orders by Status
> Returns shop orders grouped by status with pagination support and order counts.\
> \
> \*\*Three usage modes:\*\*\
> \
> 1\. \*\*Initial load\*\* (no \`page\`, no \`status\`): Returns first page of orders for every status (\`all\`, \`pending\`, \`paid\`, \`failed\`) plus total counts. Use this on first screen load.\
> 2\. \*\*Paginated "all"\*\* (\`page\` provided, no \`status\` or \`status=all\`): Returns a specific page of all orders under the \`all\` key.\
> 3\. \*\*Paginated per status\*\* (\`page\` and \`status\` provided): Returns a specific page of orders for that status under the corresponding key.\
> \
> Orders are sorted by ID descending (newest first).
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"ShopOrder":{"type":"object","required":["uuid","shopId","amount","currency","title","description","status","successUrl","failUrl","paymentUrl","createdAt","period"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID this order belongs to"},"amount":{"type":"integer","format":"int64","description":"Order amount in smallest currency units (cents/kopecks)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"title":{"type":"string","description":"Order title (max 100 UTF-16 characters)"},"description":{"type":"string","description":"Order description (max 300 UTF-16 characters)"},"status":{"type":"string","description":"Order status","enum":["pending","paid","failed"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"successUrl":{"type":"string","format":"uri","description":"Redirect URL on successful payment"},"failUrl":{"type":"string","format":"uri","description":"Redirect URL on failed payment"},"paymentUrl":{"type":"string","format":"uri","nullable":true,"description":"Web URL for customer to complete payment in a browser.\n`null` for OnlyStars orders — they can only be paid inside Telegram via `webappPaymentUrl`.\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment"},"createdAt":{"type":"string","format":"date-time","description":"Order creation timestamp in ISO 8601 format"},"comment":{"type":"string","description":"Optional comment for the order"},"period":{"type":"string","description":"Billing period for recurring orders","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"memberStatus":{"type":"string","description":"Recurring subscription status (only for recurring orders)","enum":["active","cancelled"]},"memberExpiresAt":{"type":"string","format":"date-time","description":"Recurring subscription expiration date in ISO 8601 format (only for recurring orders)"},"lastPaidTransactionAt":{"type":"string","format":"date-time","nullable":true,"description":"Date of the last paid transaction in ISO 8601 format. Null if no transactions exist."},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars (0 if not set)"},"onlyStars":{"type":"boolean","description":"Whether this order only accepts Telegram Stars payment"},"image":{"type":"object","nullable":true,"description":"Order image displayed in Telegram Stars invoices and transactions. Null if no image is set.","properties":{"id":{"type":"integer","description":"Image ID"},"path":{"type":"string","format":"uri","description":"Image URL"},"thumbnail":{"type":"string","description":"Base64-encoded thumbnail"},"width":{"type":"integer","description":"Image width in pixels"},"height":{"type":"integer","description":"Image height in pixels"},"fileType":{"type":"string","description":"File type","enum":["image","video"]}}}}},"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":{"/shop/orders_by_status":{"get":{"summary":"Get Shop Orders by Status","description":"Returns shop orders grouped by status with pagination support and order counts.\n\n**Three usage modes:**\n\n1. **Initial load** (no `page`, no `status`): Returns first page of orders for every status (`all`, `pending`, `paid`, `failed`) plus total counts. Use this on first screen load.\n2. **Paginated \"all\"** (`page` provided, no `status` or `status=all`): Returns a specific page of all orders under the `all` key.\n3. **Paginated per status** (`page` and `status` provided): Returns a specific page of orders for that status under the corresponding key.\n\nOrders are sorted by ID descending (newest first).\n","tags":["Methods"],"parameters":[{"name":"status","in":"query","description":"Filter by order status. When omitted and `page` is not provided, returns all statuses.\nWhen set to `all` or omitted with `page`, returns all orders.\n","required":false,"schema":{"type":"string","enum":["all","pending","paid","failed"]}},{"name":"page","in":"query","description":"Page number (1-based). When omitted, triggers the initial grouped load.","required":false,"schema":{"type":"integer","minimum":1}},{"name":"size","in":"query","description":"Number of orders per page (default 20, max 100)","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"dateFrom","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"Start date (inclusive) in UTC, format yyyy-mm-dd"},{"name":"dateTo","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"End date (inclusive) in UTC, format yyyy-mm-dd"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["counts","orders","nextFrom"],"properties":{"counts":{"type":"object","description":"Total order counts per status","required":["all","pending","paid","failed"],"properties":{"all":{"type":"integer","format":"int64","description":"Total number of orders across all statuses"},"pending":{"type":"integer","format":"int64","description":"Number of pending orders"},"paid":{"type":"integer","format":"int64","description":"Number of paid orders"},"failed":{"type":"integer","format":"int64","description":"Number of failed orders"}}},"orders":{"type":"object","description":"Orders grouped by status key. On initial load, contains keys `all`, `pending`, `paid`, `failed`.\nOn paginated request, contains only the requested status key (e.g. `all` or `paid`).\n","additionalProperties":{"type":"array","items":{"$ref":"#/components/schemas/ShopOrder"}}},"nextFrom":{"type":"string","description":"Next page number as string. Empty string if no more pages."}}}}}},"400":{"description":"Bad request (invalid status parameter)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop Order
> Returns full details of a specific shop order by its UUID. Includes member status and image. Only accessible by the shop owner.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"ShopOrder":{"type":"object","required":["uuid","shopId","amount","currency","title","description","status","successUrl","failUrl","paymentUrl","createdAt","period"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID this order belongs to"},"amount":{"type":"integer","format":"int64","description":"Order amount in smallest currency units (cents/kopecks)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"title":{"type":"string","description":"Order title (max 100 UTF-16 characters)"},"description":{"type":"string","description":"Order description (max 300 UTF-16 characters)"},"status":{"type":"string","description":"Order status","enum":["pending","paid","failed"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"successUrl":{"type":"string","format":"uri","description":"Redirect URL on successful payment"},"failUrl":{"type":"string","format":"uri","description":"Redirect URL on failed payment"},"paymentUrl":{"type":"string","format":"uri","nullable":true,"description":"Web URL for customer to complete payment in a browser.\n`null` for OnlyStars orders — they can only be paid inside Telegram via `webappPaymentUrl`.\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment"},"createdAt":{"type":"string","format":"date-time","description":"Order creation timestamp in ISO 8601 format"},"comment":{"type":"string","description":"Optional comment for the order"},"period":{"type":"string","description":"Billing period for recurring orders","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"memberStatus":{"type":"string","description":"Recurring subscription status (only for recurring orders)","enum":["active","cancelled"]},"memberExpiresAt":{"type":"string","format":"date-time","description":"Recurring subscription expiration date in ISO 8601 format (only for recurring orders)"},"lastPaidTransactionAt":{"type":"string","format":"date-time","nullable":true,"description":"Date of the last paid transaction in ISO 8601 format. Null if no transactions exist."},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars (0 if not set)"},"onlyStars":{"type":"boolean","description":"Whether this order only accepts Telegram Stars payment"},"image":{"type":"object","nullable":true,"description":"Order image displayed in Telegram Stars invoices and transactions. Null if no image is set.","properties":{"id":{"type":"integer","description":"Image ID"},"path":{"type":"string","format":"uri","description":"Image URL"},"thumbnail":{"type":"string","description":"Base64-encoded thumbnail"},"width":{"type":"integer","description":"Image width in pixels"},"height":{"type":"integer","description":"Image height in pixels"},"fileType":{"type":"string","description":"File type","enum":["image","video"]}}}}},"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":{"/shop/orders/{orderUuid}":{"get":{"summary":"Get Shop Order","description":"Returns full details of a specific shop order by its UUID. Includes member status and image. Only accessible by the shop owner.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopOrder"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (order belongs to another shop)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order or shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop Order Status
> Returns the current status of a specific shop order by its UUID. Only accessible by the shop owner.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"/shop/orders/{orderUuid}/status":{"get":{"summary":"Get Shop Order Status","description":"Returns the current status of a specific shop order by its UUID. Only accessible by the shop owner.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","description":"Order status","enum":["pending","paid","failed"]}}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (order belongs to another shop)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order or shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Cancel Recurring Shop Order
> Cancels a recurring shop order subscription. Only accessible by the shop owner or authorized managers.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"/shop/orders/{orderUuid}/cancel":{"post":{"summary":"Cancel Recurring Shop Order","description":"Cancels a recurring shop order subscription. Only accessible by the shop owner or authorized managers.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Order cancelled successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message"],"properties":{"success":{"type":"boolean","description":"Whether the operation was successful"},"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":"Forbidden (access denied)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order, shop, or recurring subscription not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop Order Transactions
> Returns a paginated list of transactions for a specific shop order. Only accessible by the shop owner or authorized managers.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"Transaction":{"type":"object","required":["id","type","amount","currency","createdAt","total"],"properties":{"id":{"type":"integer","format":"uint64","description":"Transaction ID"},"type":{"type":"string","description":"Transaction type"},"objectId":{"type":"integer","format":"uint64","description":"Related object ID"},"amount":{"type":"number","format":"double","description":"Transaction amount in currency units (e.g., EUR, RUB)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"createdAt":{"type":"integer","format":"int64","description":"Transaction creation timestamp (Unix timestamp in seconds)"},"serviceFee":{"type":"number","format":"double","description":"Service fee amount"},"total":{"type":"number","format":"double","description":"Total amount after fees"},"paymentMethod":{"type":"string","description":"Payment method used"},"isRefunded":{"type":"boolean","description":"Whether the transaction has been refunded"},"isRefundable":{"type":"boolean","description":"Whether the transaction can be refunded"},"isRecurring":{"type":"boolean","description":"Whether this is a recurring payment transaction"},"shopOrder":{"type":"object","description":"Related shop order details (included for shop order transactions)","properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"title":{"type":"string","description":"Order title"},"description":{"type":"string","description":"Order description"},"amount":{"type":"number","format":"double","description":"Order amount in currency units"},"currency":{"type":"string","description":"Currency code (lowercase)"},"status":{"type":"string","description":"Order status","enum":["pending","paid","failed"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"successUrl":{"type":"string","format":"uri","description":"Success redirect URL"},"failUrl":{"type":"string","format":"uri","description":"Failure redirect URL"},"createdAt":{"type":"integer","format":"int64","description":"Order creation timestamp (Unix timestamp in seconds)"},"comment":{"type":"string","description":"Order comment (optional)"},"period":{"type":"string","description":"Billing period","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"shopName":{"type":"string","description":"Shop name"},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars (0 if not set)"},"onlyStars":{"type":"boolean","description":"Whether this order only accepts Telegram Stars payment"}}}}},"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":{"/shop/orders/{orderUuid}/transactions":{"get":{"summary":"Get Shop Order Transactions","description":"Returns a paginated list of transactions for a specific shop order. Only accessible by the shop owner or authorized managers.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"startFrom","in":"query","description":"Pagination offset (number of records to skip)","required":false,"schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["transactions","nextFrom"],"properties":{"transactions":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"nextFrom":{"type":"string","description":"Offset for the next page. Empty string if no more pages"}}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Forbidden (access denied)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order or shop not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Refund Shop Order Transaction
> Initiates a refund for a specific transaction of a shop order. Only accessible by the shop owner or authorized managers. Only sell transactions from paid orders can be refunded.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Methods","description":"Shop methods for managing orders and recurring payments.\n\n## Payment Methods\n\nAvailable payment methods depend on the order configuration:\n\n**Standard orders** (`onlyStars: false`):\n| Method | Availability |\n|--------|-------------|\n| Bank cards | Always available |\n| SBP | Available when seller has SBP enabled (can be enabled by request to Tribute support). Only for one-time orders (`period: \"onetime\"`) |\n| Wallet Pay (TON) | Always available |\n| Telegram Stars | Only when `starsAmount > 0`, period is `onetime` or `monthly`, and `tokenCharging` is disabled |\n\n**OnlyStars orders** (`onlyStars: true`, `tokenCharging` disabled, only `onetime` and `monthly` periods):\n| Method | Availability |\n|--------|-------------|\n| Telegram Stars | Always available |\n| Bank cards | Card-to-Stars flow. Available when `starsAmount >= 50` |\n\n> **Note:** Pix and PayPal are **not available** for shop orders.\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":{"/shop/orders/{orderUuid}/transactions/{txId}/refund":{"post":{"summary":"Refund Shop Order Transaction","description":"Initiates a refund for a specific transaction of a shop order. Only accessible by the shop owner or authorized managers. Only sell transactions from paid orders can be refunded.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"txId","in":"path","description":"Transaction ID (must be a sell transaction)","required":true,"schema":{"type":"integer","format":"uint64"}}],"responses":{"200":{"description":"Refund initiated successfully","content":{"application/json":{"schema":{"type":"object","required":["success","message","status"],"properties":{"success":{"type":"boolean","description":"Whether the operation was successful"},"message":{"type":"string","description":"Success message"},"status":{"type":"string","description":"Refund status","enum":["initiated"]}}}}}},"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":"Forbidden (access denied)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order, shop, or transaction not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error (refund processing failed)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# 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://wiki.tribute.tg/for-shops/api/methods.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.