# About the Tribute bot
**Tribute** is a [Telegram bot](https://t.me/tribute/app?startapp=lL2NyZWF0b3IvcHJvZHVjdHM_utm_us_website_um_owned_ucp_main_uc_wiki_ut_eng) with which you can make paid subscriptions to your channel and accept donations from your subscribers.
{% hint style="info" %}
**Tribute** news and tips —[ https://telegram.me/TributeNewsEN](https://telegram.me/TributeNewsEN)
For questions of co-operation —
{% endhint %}
# Subscriptions
**Subscriptions** are one of the ways to monetize Telegram channels. You can create a subscription for both private and public channels.
**You can create subscriptions for**:
If you have a **private channel**, a subscription allows you to access your channel and the content in it.
If you have a **public channel**, a subscription allows you to support your channel with regular payments.
# Gift Subscription
You can now offer a subscription to your private channel as a gift. It’s a convenient and thoughtful option for anyone looking for a great last-minute present.
Nothing needs to be enabled manually — the “Buy as a gift” option is available automatically.
### How to use
1. Select “Buy as a gift” during the subscription checkout — the option appears at the payment step.
2. Confirm the payment and receive a unique link that the recipient will use to activate the gift subscription.
3. Send the link to the recipient so they can access the subscription right away.
# How to create a subscription
1. Open «Menu» in the **Tribute** bot.
2. Select the channel where you want to create a subscription.
3. Click «Subscription».
4. Specify the period (one-time, weekly, monthly, 3 or 6 months, or annual subscription), amount and currency of the subscription.
5. Next, specify the name, description of the subscription and the text of the button.
6. Click «Create».
# Subscription publishing
Tribute offers 3 ways to share your subscriptions. We’ve outlined them below — just choose the one that works best for you.
{% hint style="info" %}
Make sure to use one of these official methods. Sharing a direct invite link to a private group won’t trigger the subscription — and access won’t work properly.
{% endhint %}
### How to share a subscription by mentioning @Tribute in a channel or chat
1. In any Telegram channel, group, or direct message, type @Tribute and press the spacebar.
2. Choose the subscription you want to share, or select a unified link that leads to all your available subscriptions.
### How to share a subscription as a standalone post in Telegram
1\. Go to “Channels & Groups” in your Creator dashboard.
2\. Select the relevant channel and subscription.
3\. Tap “Share” at the bottom — this will open a window for creating a separate post.
4\. Choose where to send it: a channel, chat, or personal message.
5\. Confirm — the subscription will be published as a standalone post.
### How to share a subscription via a link
1\. Go to “Channels & Groups” in your Creator dashboard.
2\. Select the channel and subscription you want to share.
3\. Tap “Links”.
4. Choose the appropriate option and tap the icon on the right:
• Telegram link (best for use inside Telegram)
• Web link (deal for external platforms)
5\. Done! The link has been copied to your clipboard — now just paste it where you need using Ctrl + V or the Paste function.
### What happens next?
When someone follows the link, they’ll see an invoice page with the subscription price, currency, and billing cycle.
Once they complete the payment and request access to the private channel, the bot will automatically approve their request.
You and the subscriber will both receive a confirmation notification.
\
# How to edit subscription
1. Open your Creator Dashboard
2. Open the Subscriptions section
3. Select a channel or group.
4. Select desired subscription.
5. Click the Edit button
6. Adjust the settings on the screen and click the Save button
{% hint style="info" %}
You can edit the title and description of your subscription, the discount, the button text, and the period. The updated conditions will only apply to new subscribers.
{% endhint %}
# How to delete subscription
1. Open your Creator Dashboard
2. Open the Subscriptions section
3. Select the desired channel
4. Select the desired subscription
5. Click the More button
6. Click the Delete button
7. Confirm by clicking Delete again
{% hint style="info" %}
Once a subscription is deleted, it will stop renewing with subscribers, but they will still have access until the subscription expires.
{% endhint %}
# Trial Subscription Period
A trial subscription allows users to access a private channel for free for a limited time — 1, 12, or 24 hours, or 3 or 7 days.\
This feature helps potential subscribers explore your content before paying and increases conversion to paid subscriptions.
**How to enable a trial period**
1. Go to the **“Payments”** section when creating or editing a subscription.
2. Activate the **“Trial period”** option.
3. Set the desired trial duration — 1, 12, or 24 hours, or 3 or 7 days.
After linking a payment card, the user will receive free access for the selected period.\
Once the trial period ends, the subscription will automatically renew as a paid one (unless the user cancels it in advance).
If you add a trial period while editing an existing subscription, it will apply only to **new subscribers**.
# Higher Price for the First Subscription Period
We’ve added a new feature that allows creators to set a higher price for the first billing period of a subscription.
Example:
* First month — 100 €
* Second and subsequent months — 50 €
Subscribers will see the correct pricing directly in the interface and can pay through Tribute.
### Who This Is Useful For
#### Course creators
You can make the first month more expensive (for example, to cover the cost of access to course materials), while keeping later months cheaper to improve retention.
#### Creators whose value is concentrated in the first moments
For example, if you offer access to cheap tickets, flash deals, early releases, or other time-sensitive benefits, the subscription provides immediate value from day one.
### How to Enable It
1. Open Subscriptions in your creator profile.
2. Click New subscription and add channels or groups.
3. Click Set up Payments.
4. Select Add Period.
5. Choose the billing frequency and price.
6. In the First month section, select “More expensive”.
7. Enter the desired price for the first month.
8. Save your changes.
\
# Deferred subscriber removal for failed payments
Each month, around 50,000 subscriptions are canceled due to insufficient funds on the subscriber’s card.
\
To reduce this number, we introduced a deferred removal system: within seven days after a failed payment attempt, the service continues trying to charge the subscriber (previously, attempts were made only within one day).
\
Subscribers whose payments still do not go through are automatically removed from the channel only after the seven-day period ends.
# Promo codes for subscriptions
We’ve added a new tool for running promotions and attracting new subscribers — promo codes. These are unique codes that give users a discount when purchasing their first subscription.
#### How to create a promo code:
1. Go to the **“Promo Codes”** section in your Tribute creator dashboard.
2. Click **“Create Promo Code.”**
3. Choose which subscription the promo code will apply to. If you have only one subscription, it will open automatically.
4. Fill in the following fields:
| Field | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Name** |
Internal name or description of the promo campaign
Only visible to you
|
| **Promo Code** |
A unique code, 4–10 characters long
You can use a randomly generated code or enter your own
|
| **Discount** |
Discount percentage — from 1% to 99%
Default is 50%
|
| **Validity Period** | Start and end date and time when the promo code will be active. |
| **Activation Limit** |
Maximum number of times the promo code can be used
Default is 100
|
5. Click **“Save.”**
That’s it! You can now copy the promo code and share it with your audience on any platform.
#### Promo code usage options:
* **Add it to visuals** — use the code on banners, both online and offline.
* **Share a direct link** — it will lead to the subscription page with the promo code auto-filled and the discount automatically applied.
You can edit promo code settings later — for example, increase the activation limit.
***
{% hint style="info" %}
#### Important details:
{% endhint %}
* Promo codes only apply to **first-time subscription payments.**
* You can **track usage statistics** for each promo code.
* The **minimum subscription price after discount** is €1.
* If a subscription includes several billing periods, the promo code applies to all of them. If the discount lowers the price in any of those periods below the €1 minimum, the discount will be automatically adjusted.
* Discounts from the promo code **do not combine** with the discount for the first billing period.
# How to offer a discount on subscriptions
Discounts apply to new subscribers only and can be set for just the initial subscription period. For instance, if you create a weekly subscription, the discount can apply for one week only. After this, subscribers will pay the full subscription price weekly.
1. Open the "Menu" in the @Tribute bot.
2. Select the channel or private group where you want to create а subscription.
3. Click "Subscription" and choose the payment method. Bank cards for subscriptions in euros. [Wallet](https://wiki.tribute.tg/for-content-creators/wallet-pay) — for cryptocurrency payments.
4. Specify the period (weekly, monthly, or yearly). One-time subscriptions cannot be discounted.
5. Specify the amount and currency of the subscription.
6. In the "Discounts" section, enable the discount option, then choose the discount amount: from 10% to 90%, but not less than the service's set [limits](https://wiki.tribute.tg/for-content-creators/fees-limits-currencies).
7. Next, specify the name, description of the subscription, and the text of the button.
8. Click "Create".
# How to offer a subscription retention discount
The discount will be applied once and only for users who choose to cancel their subscription. The subscription period remains the same: for example, if a user cancels a weekly subscription, they will receive the discount only for one week. After that, the subscriber will pay the full price on a weekly basis.
1. Open the "Menu" in the @Tribute bot and select the channel or private group where you want to create a subscription.
2. Tap "Subscription".
3. Create a name and description for the subscription and the button text. Tap "Continue".
4. Specify the period. The subscription can be weekly, monthly, or yearly. One-time subscriptions cannot have discounts.
5. Set the price and currency for the subscription, then choose the payment method and tap "Continue."
6. In the “Retention Discount” section, enable the discount option, then select the discount size: from 10% to 90%, but no less than [the service's set limits](https://wiki.tribute.tg/for-content-creators/fees-limits-currencies).
7. Tap "Create".
{% hint style="info" %}
If you want to add this discount to an existing subscription, simply tap "Edit," and in the "Discounts" section, enable "Retention Discount." Then select the discount amount: from 10% to 90%.
{% endhint %}
# Referral Program
Tribute launches a Referral program allowing you to earn additional income by inviting new creators to the platform. Share your link and receive 2% of the revenue generated by the creators who join through your link for 5 years.
### How it works
1. Go to the Referral Program section in your Tribute creator profile.
2. Read the terms, accept them, and click “Activate.”
3. Copy your referral link and share in your channels or send directly to creators.
4. Receive 2% of the revenue from each creator who joins through your link for 5 years after their first payout.
{% hint style="info" %}
You will earn a percentage of the referred creator’s revenue from subscriptions, donations, digital and physical products. Revenue from referral program and automated ads is not included.
{% endhint %}
### Activity tracking
In the “Referral" section, you can track:
* the number of creators you’ve invited,
* the accumulated balance from referrals,
### Bonus for new creators
Creators who register through your link get a bonus: + 30,000 ₽ (or equivalent in another currency) of their income commission-free.
# Bonus Campaign Terms: “New Creator Bonus”
The campaign is valid until April 30, 2026 (inclusive)
\
**To participate, you need to:**
1\. Join the Tribute affiliate program
2\. Refer a creator via your affiliate link
3\. The creator must register and start selling content
\
**Bonuses are granted when the creator reaches revenue milestones:**
→ creator earns 250$ → you get 10$
→ creator earns 1250$ → you get 60$
Only actual revenue is counted (successful paid transactions), excluding refunds and cancellations. The required revenue must be reached by April 30, 2026 (inclusive). Bonus is granted once per referred creator
\
**The campaign applies only to:**
• new affiliates (who have not previously joined the affiliate program)
• new creators (who have not previously registered on Tribute)
\
In addition, you receive 2% of the creator’s revenue for up to 5 years (according to standard affiliate program terms)
{% hint style="info" %}
Tribute reserves the right to withhold bonuses in case of fraudulent or abusive activity
{% endhint %}
\
# Referral Program Rules
## **Referral Program Rules for Engaging Creators on the Tribute Service (“Rules”)**
Effective as of August 21, 2025
1. **Company**
TRBT Limited, Registration No. HE 443898, with its registered office at Griva Digeni 51, ATHINEON COURT, Flat/Office 202, 8047 Paphos, Cyprus (hereinafter the **“Company”**).
2. **Participants**
1. **Partner** – a current creator of the Tribute service who refers new creators via their referral link.
2. **Referred Creator** – a new user who has not previously held a Tribute account and who registers through a Partner’s referral link.
3. **Program Term**
1. The program begins on September 1, 2025 and continues until further notice.
2. The Company may suspend or terminate the program at any time by publishing a notice on its official resources.
4. **Program Rules**
1. Each Partner is provided with a unique referral link in their Tribute account.
2. To qualify, a Referred Creator must register with Tribute using the Partner’s referral link.
3. Registration is valid only if the Referred Creator has not previously created a Tribute account.
4. The Partner becomes eligible for a reward once a Referred Creator starts monetizing their content, in accordance with Section 5.
5. **Rewards: Calculation and Payment**
1. **Reward Basis:** The Partner receives 5% of the total value of all successful transactions made by the Referred Creator (including subscriptions, donations, and sales of digital and physical goods).
2. The calculation is based on the transaction amount before Tribute’s service fee is deducted.
3. Exemptions. The following are excluded from the calculation:
* Refunds, chargebacks, and disputed payments
* Shipping and handling costs for physical goods
* Taxes and mandatory fees included in the purchase price
* Payouts made under the Referred Creator’s own affiliate programs
* Compensation received by the Referred Creator from third-party advertising or affiliate arrangements integrated into their content (e.g., marketplace revenue)
* Advertising and promotion costs paid by the Creator through Tribute
6. **Accrual Period**
1. Rewards accrue for twelve (12) months from the date of the Referred Creator’s first successful transaction.
2. To allow for potential refunds and disputes, accrued rewards are held for fifteen (15) days before becoming payable.
7. **Payment**
1. Payments are made twice per month: on the 25th (or the next business day) for the period from the 1st to the 15th, and on the 10th of the following month (or the next business day) for the period from the 16th to the end of the month.
2. The minimum payout threshold is the same as that specified in the Creator Agreement available at .
3. If the minimum threshold is not reached, the balance carries forward to the next payout date.
8. **Miscellaneous**
1. Participation in the program constitutes full acceptance of these Rules and of the Creator Agreement.
2. Self-referral (using one’s own referral link to register additional accounts) is prohibited.
3. Referral links may not be distributed in ways that violate applicable law or the rules of third-party platforms (e.g., spam).
4. In the event of a violation, the Company may exclude the Partner from the program and cancel any accrued but unpaid rewards.
5. The Company is not responsible for any tax liabilities arising from receipt of rewards. Partners are solely responsible for calculating and paying any taxes owed.
9. **Amendments**
1. The Company may amend these Rules at any time without prior individual notice.
2. Amendments take effect upon publication on the Company’s official resources. Participants are responsible for monitoring updates.
10. **Governing Law and Dispute Resolution**
All disputes or claims arising out of or in connection with this program will be resolved in accordance with the laws of the Republic of Cyprus, as provided in the Creator Agreement.
# Private Chats
Private Chats are a tool for paid communication with your audience inside [Tribute.](https://t.me/tribute/app?startapp=lL2NyZWF0b3IvcHJvZHVjdHM_utm_us_website_um_owned_ucp_private-chats_uc_wiki_ut_eng)\
This feature allows creators to have one-on-one conversations with users and use them as a separate monetization format.
A chat with a creator can be used for:
* personal feedback or reviews
* answering audience questions
* a premium subscription tier where users can ask the creator a set number of questions
* private consultations
#### Chat Scenarios
1. **Paid Dialogues**\
A user pays for access to the chat and communicates with you for a limited time. If they want to continue the conversation, they pay for a new dialogue.
2. **Paid message for everyone**\
Any user can message the creator via a link,\
but they must pay before sending the message.
3. **Free message → paid reply**\
A user can send a message for free,\
and the creator can reply with a paid message.
The reply can include additional materials, such as:
* photos
* files
* an image with a written response
The content becomes available only after the user completes the payment.
4. **Paid messages for subscribers only**\
Only subscribers can message the creator,\
and each message must be paid for before it’s sent.
5. **Free message for subscribers → paid reply**\
Subscribers can message the creator for free,\
and the creator can send a paid reply.
#### Additional Features
**Changing the message price**
During a conversation, the creator can adjust the price of the next messages.
This is useful if the conversation turns into:
* a consultation
* a personal review
* a longer discussion
This feature works when a message includes:
* a photo
* an image
* a screenshot with a written response
Chat history is saved, and the paid content scenario can be changed at any time.
#### How to create a Private chat
1. Go to the **Private Chats** section in the creator profile.
2. Click **Set up**.
3. Fill in the chat details:
* Name
* Welcome message
4. Choose whether a subscription is required to access the chat.\
If required, select it from the list.
5. Set up payment settings: currency, price, and payment methods.
6. Click **Done**.
7. Once the chat is created, share the link with your audience.
# Creator’s Page
We’ve added the ability to add your Creator’s Page.
With this new feature, all key information is gathered in one place: the creator’s photo or video and bio, subscriptions, products, donations, social media links, and reviews. Everything is neatly organized and easy for your subscribers to use.
#### Why is this useful?
* To simplify sales
* To increase visibility
* To give your audience an easy way to support you
#### How to add Creator’s Page
1. Open the Creator’s Page section.
2. Click Create Page.
3. Fill in the required sections and click Preview.
4. Like what you see? Click Save.
5. It’s time to share your page!
* Click the “Share” button to quickly publish it to your Telegram channel
* or go to “Links” and copy the Telegram link or web link to share it on any platform.
Creator’s page can be edited at any time after publication.
# Automatic Posting for Subscriptions and Donations
Automatic posting lets you publish subscription and donation posts to selected channels on a schedule — without doing it manually each time.
## How to Enable Automatic Posting
Follow these steps to turn on auto-posting:
#### 1. Open the subscription or donation
Go to the settings of the subscription or donation.
#### 2. Turn on auto-posting
Switch on the “Auto-posting” toggle to activate the feature.
#### 3. Choose your channels
You’ll see only the channels where the Tribute bot is added as an admin.\
Select one or several channels — your posts will appear in all of them at once.
If you don’t have any channels with the Tribute bot set as admin, auto-posting cannot be enabled.
#### 4. Set the schedule
Choose:
* how often to post (weekly or monthly),
* the day or date,
* the time of publication.
#### 5. Save your settings
After saving, you will see:
* whether auto-posting is enabled,
* the date and time of the next scheduled post.
If you choose a time that has already passed, the system will automatically move the first publication to the next possible slot.
## How Automatic Posting Works
When it’s time to publish, Tribute does the following:
#### 1. Checks channel availability
* If the bot is in the channel and still has admin rights, the post will be published.
* If the bot has been removed or lost permissions, that channel is automatically excluded from auto-posting.
If multiple channels are selected and one becomes unavailable, posts will continue publishing to the remaining ones.\
If the unavailable channel was the only one — auto-posting will be turned off entirely.
#### 2. Builds the post using up-to-date data
Each post is generated from scratch and includes current:
* title,
* description,
* price,
* cover,
* buttons.
Any changes you make to the subscription or donation will be reflected in the next automatic post.
## Simultaneous Posts
If several auto-posts are scheduled for the same time, that’s completely fine.\
There’s no limit to how many auto-posts can be published in a single channel.
## If Something Goes Wrong
The system handles errors automatically:
* If a channel is temporarily unavailable or Telegram returns an error, that specific post will be skipped — the rest will continue as planned.
* If a channel becomes permanently unavailable (the bot is removed or loses rights), it’s removed from the auto-posting setup;
* if no channels remain, auto-posting will be disabled entirely.
# Raffle
Raffle is a powerful tool for creators to attract new subscribers, boost engagement in their channel, drive sales of digital and physical products, and generate extra hype around their brand.
{% hint style="info" %}
Example: Participants who paid a monthly subscription and bought a digital product get a chance to win exclusive merch.
{% endhint %}
### How it works
1. **Creators set up the raffle:**
* Add tasks for participants
* Define the prizes, dates, and number of winners;
2. **Participants complete tasks.**
* Subscribe to a free channel;
* Pay for a subscription to a paid channel;
* Purchase a digital product;
* Purchase a physical product or item from a collection;
* Or make a donation.
{% hint style="info" %}
Each task earns tickets (for example, 1 ticket per 100 RUB / 1 EUR). The more tickets a participant has, the higher their chances of winning.
{% endhint %}
3. **Winners are selected automatically and notified.**
4. **Creators send the prizes to winners.**
### How to create a raffle on Tribute
1. Go to the “Raffles” section in your Tribute creator profile.
2. Read the terms and accept.
3. Enter the raffle title, dates, number of winners, description, cover image, and button text. Click “Go to task selection.”
4. Select your Tribute product, add a task, and click “Continue.” Add any remaining tasks the same way if needed.
5. Check that all information is correct and click “That’s correct, continue.”
5. Click “Share.”
7. Done! Your raffle is now live in your channel.
### Selecting winners
* Once the raffle ends, winners are selected automatically.
* You can view them in a dedicated section.
{% hint style="info" %}
For a successful raffle, choose prizes that your audience will genuinely want, include tasks that align with your goals, and share the raffle in your channel and across other social media to maximize participation.
{% endhint %}
\
# Tribute Energy
We have launched the Tribute Energy feature. Now, with each purchase, both the creator and subscriber will earn energy. The higher the purchase amount, the greater the chance of earning maximum energy.
Creators with the highest scores will appear in a special ranking – the leaderboard. Soon, energy can be exchanged for rewards.
#### How to connect to Tribute Energy?
1. Open the Tribute bot and click on the lightning bolt icon in the top right corner of the balance screen.
2. Add a nickname.
3. Upload a photo.
4. Add a short description of your activity.
5. Choose a channel subject from the list.
6. Add any Telegram link (a link to an introductory post, an open channel, or a subscription to a closed channel). This link allows users to learn more about you when they see you on the leaderboard.
7. Submit your application for moderation. Once approved, the feature will automatically be available in your profile.
# LinkHub
LinkHub is a convenient tool that allows creators to gather all their important links on one page.
**How to create my LinkHub?**
1. Go to the "LinkHub" section in the author dashboard and click "Create."
2. Add a title and description.
3. Add a photo to make your LinkHub more vibrant and recognizable.
4. Upload a preview image for social media – this will be visible when you share the link.
5. Add links: In the top section, you can add links to Tribute products (subscriptions, donations, digital goods, etc.), and in the bottom section, you can add links to any other platforms (such as social media profiles).
6. After creating your LinkHub, you’ll get a unique link that you can instantly copy and use for your posts.
**How to edit my LinkHub?**\
If you need to make changes, you can edit:
* The content (add or remove links).
* The description and photo
* To change the order of the links, simply press and hold any link, then drag it up or down.
Now all the links to your products are gathered in one place – and it’s very convenient for both you and your followers!
# Manager role
**The manager role allows authors to delegate the management of monetization settings and products without giving access to their personal Telegram account.**\
Simply add a manager and choose which sections they will have access to. Managers can work with product settings, manage physical products orders, and handle other monetization tasks.
{% hint style="info" %}
Currently, the manager role is available for managing physical products, subscriptions ans donations.
{% endhint %}
### How to Add a New Manager:
1. Go to the "Managers" section.
2. Add a name for your account.
* Use your brand or channel name to make it easier for the manager to navigate the list.
* Click "Save."
3. Click "Add Manager."
4. Assign access rights:
* After adding a manager, you'll see a list of available products and sections that you can give access to: subscriptions, donations, physical products, etc.
* Click "Grant Full Access" to give access to all features at once.
* If you need to provide partial access, manually select the relevant sections and click "Save."
You can remove a manager's access at any time through the same section.
5. Click "Copy Link" and send it to your manager.
6\. Go to the Tribute bot and approve the manager’s request to manage the channel.
7\. That’s it!
# Physical products
Now with Tribute, you can sell not only digital products but also physical ones!
### What does this mean?
We’ve added the ability to create product listings, add sizes, colors, and materials, track order statuses, and automate customer interactions — just like on familiar marketplaces.\
It’s a great channel to sell merch and branded products to your community!
### How to create a physical product?
1. Go to the “Physical Products” tab – “Add Physical Product.”
1. Add the product name, description, and image.
3. Set the currency and payment methods.
4. Click “Add Variant” and, on the next screen, enter the price, quantity, and product attributes – for example, color or size.
5. Click “Save.”
6. Done!
### And how do you publish it?
1. Start by typing @Tribute in any Telegram chat.
2. Select the physical good from the pop-up window to share.
# Collections
Collections allow you to group products thematically and present them as a separate page with product cards.
#### How to create a collection?
1. Open the Tribute mini app, go to the **Physical Products** section and open the **Collections** tab.
2. Click **Create Collection.**
3. Add a title, description, and cover image, and choose a button text.
4. Add the products you want to include in the collection.
5. Click **Create Collection**.
Done! Now, you can share your collection in your channel: simply type @tribute and press the space bar. Your collection will appear in the Tribute product list.
#### How to edit a collection?
Want to add or remove products? You can edit the collection anytime by clicking Edit.
# Bulk Product Upload
Now you can fill out the Excel template and upload your entire product range in a single file. Fast and convenient!
### How to upload products:
1. Go to the “Physical Products” section in your Tribute Creator dashboard.
2. Open the “Products” section.
2. Click "Import from file" above the product list.
2. Download the Excel template.
4. Fill it out according to the instructions:
| **Field Name** | **Description** |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Product Id** |
Unique identifier for the product
Each product must have a different value; otherwise, the data will merge into a single item.
If you're adding variants of the same product (e.g., different sizes or colors), all variant rows should have the same Product ID — this way, the system will create one product with multiple options after the file is uploaded.
|
| **Product Name** |
The name of the product visible to customers
Maximum 50 characters
|
| **Description** |
Full description of the product in plain text
Maximum 300 characters
|
| **Currency** |
Currency of the product price
Use RUB for rubles or EUR for euros
|
| **Button Text** |
Text shown on the order form button
E.g., “Buy” or “Pre-order”
Maximum 20 characters
|
| **Cover Image Link** |
Link to the cover image shown when the product is published in a chat or channel
Recommended size: 1024×1024 pixels
|
| **Price** |
Price per unit of the product in the specified currency
Use a dot as the decimal separator (e.g., 1999.99)
|
| **Stock** | Number of units available for sale. |
| **Attribute1** |
Name of the first variant attribute — works together with the Value1 column
E.g., “Color”
Leave empty if not needed
|
| **Value1** |
Value of the first attribute
E.g., “Red”
|
| **Attribute2** |
Name of the second variant attribute — works together with the Value2 column
E.g., “Size”
Leave empty if not needed
|
| **Value2** |
Value of the second attribute
E.g., “L”
|
| **Length, cm** |
Product length in centimeters (for shipping cost calculation)
Numbers only
|
| **Width, cm** |
Product width in centimeters (for shipping cost calculation)
Numbers only
|
| **Height, cm** |
Product height in centimeters (for shipping cost calculation)
Numbers only
|
| **Weight, gram** |
Product weight in grams (for shipping cost calculation)
Numbers only
|
| **Image Links** |
Links to images or videos for the product card
Recommended size: 1024×1024 pixels
Separate multiple links with a space
|
5. Go back to Tribute and upload the completed Excel file.
{% hint style="info" %}
**Please note:** each upload creates new products!
* We recommend testing the upload with 1–2 products first.
* You cannot edit or delete existing products via a new upload — even if the Product ID matches.
{% endhint %}
# FAQ
**Can I create a referral offer for physical products?**\
Not yet, but we’ll add this option soon.
**Can I sell goods on Tribute without using the physical products feature?**\
No, it won’t pass moderation.
**Who handles the delivery of physical products?**\
Currently, the seller is responsible for delivery, but we will integrate popular delivery services soon.
**What if the item is wrong or of poor quality?**\
You should contact the seller. The seller and the delivery service they use are responsible for resolving such issues.
**Why should I pay a commission if I handle everything myself?**\
Tribute allows you to sell products or set up an entire store within an existing community. You won’t have to redirect traffic to external sites, which usually significantly decreases conversion rates. Tribute also provides seamless global payment options for your products—just a few clicks within the messenger using any bank cards.
**What about international shipping?**\
Currently, the seller manages delivery and must arrange it directly with the delivery services.
**How should I price shipping when the cost varies depending on the destination?**\
We are working to make this feature more convenient. For now, you can issue a separate charge, e.q. through a donation.
**Can I include links to other marketplaces in the physical goods section?**\
No, this is not allowed.
**Can I resell other people's items? For example, second-hand luxury goods?**\
Yes, you can.
**What is the service fee for the physical products feature?**\
8%.
# Preliminary Shipping Cost Calculation
To make it easier to sell physical products with Tribute, we have added a preliminary shipping cost calculation feature in the bot.
### How it works:
#### Before the order:
1. Go to Physical products – Delivery Settings.
2. Add the shipping address.
3. Select the shipping countries.
4. Activate shipping cost calculation.
5. **Connect an available shipping service.** Currently, only one is available, but more will be added soon!
6. **Specify the product parameters:** Fill in the information about the weight and dimensions of each product.
#### During the order:
7. **Collect customer data:** Have the customer enter the delivery address and choose the method of receiving the product (courier or pickup point).
8. **Calculate the cost:** Calculate the total cost (product + shipping) and add it to the customer's invoice.
9. **Process the payment:** After the customer pays for the order, receive a notification about the order.
#### After the order:
10. **Organize product delivery:** Either call a courier yourself or go to the pickup point, providing the address given by the customer, and pay for the delivery.
10. **Receive payment:** After 30 days (considering the return policy), receive payment from us for the product and delivery.
**Commission:** We take a commission from the total amount (product + shipping). A special offer is currently available: we are offering a reduced commission on physical products (5% instead of 10%) for 6 months for any sale made till the end of January.
# Automatic Partner Ads
You can now earn with Tribute through automatic placement of partner ad posts.\
Our first partner is **Yandex Market**.
{% hint style="info" %}
This tool is currently in testing — we're actively working on improvements and would love to hear your feedback.
{% endhint %}
#### How to Enable It
1. Go to the **"Automatic Ads"** section in your Tribute creator dashboard.
2. Agree to the terms and click **"Enable"**.
3. Choose the channel where you'd like the ads to be published.
4. Done! Starting now, one ad post will automatically appear in your channel twice a week.\
Each post features **top-rated, verified products** from Yandex Market.
You’ll earn **5% of any purchases** made through your links within three days after the click.\
The maximum earning per order from a single buyer is **₽4,500**.
For more on payout terms and conditions, see below.
### FAQ
Can I choose which products are published?
Not at the moment — product selection and category settings are not yet available.\
But this feature is still evolving, so stay tuned for updates.
Can I set ads to post daily?
Currently, ads are published **automatically twice a week** between **10:00 and 17:00 (Moscow time)**.\
There must be **at least three days** between two ad posts.
Do I only earn from the specific products shown in the ads?
No — you’ll earn **5% from *****any***** purchases** made on the marketplace within three days after a user clicks your link.\
The max you can earn from a single buyer’s order is **₽4,500**.
What do the status labels mean in the Automatic Ads stats?
* **Confirmed** — This amount will be paid out on the next scheduled date. See below for payout details.
* **In Progress** — These earnings will be confirmed after successful delivery and a 14-day hold (to account for returns or cancellations).
* **Paid** — The total amount you’ve already earned and received through this tool.
* **Cancelled** — The percentage of orders that were canceled or returned within 14 days after purchase.
How Payouts Work?
**Holding Period:**
After delivery, the earnings are frozen for **14 days** to account for possible returns or cancellations.\
If there are none, the funds become eligible for payout.
#### Payout Dates:
* For orders delivered and past the 14-day hold **between the 1st and 15th** — payout is on the **25th of the same month**.
* For orders cleared **between the 16th and the end of the month** — payout is on the **10th of the next month**.
**Examples:**
* Order delivered on **June 2** → hold until **June 16** → payout on **July 10**
* Order delivered on **May 20** → hold until **June 3** → payout on **June 25**
# Affiliate program
The Tribute affiliate program helps creators attract more subscribers and increase their income, while partners earn money by recommending creators' offers.
### How does it work?
1. A **creator** sets up an offer and specifies what percentage of income from new paying audience members they’re willing to share.
2. **Partners** choose suitable offers and promote them through their channels to attract new paying audience members.
3. When someone makes a purchase through a partner’s recommendation, the **partner receives their share** of the income.
4. The most popular offers make it to the top list.
### Instruction for creators
How can a creator create an offer and attract a new audience?
1. Go to the “[Affiliate Program](https://t.me/tribute/app?startapp=lL29mZmVycw==)” section.
2. Select “[Expand Your Audience](https://t.me/tribute/app?startapp=lL29mZmVycy9jcmVhdG9y).”
3. Click “Create Offer.”
4. Choose the product you want to promote.
5. Add a title and description. For example, explain your content theme or preferred traffic channels.
6. Next, set the offer’s validity period\* and the percentage you’re willing to share with the partner.
7. Click “Create.”
{% hint style="info" %}
\*The validity period of the offer starts from the first purchase made through the referral link.
{% endhint %}
**Done!** You’ll see a screen with the offer details, including the number of referrals, total income, validity period, and offer conditions.
All that’s left is to click the "Copy Link" button and share the offer with partners through any of your channels.
#### Instruction for partners
How to become a partner?
1. Go to the “[Affiliate Program](https://t.me/tribute/app?startapp=lL29mZmVycw==)” section.
2. Click “[Earn From Recommendations](https://t.me/tribute/app?startapp=lL29mZmVycy9wYXJ0bmVy)”
3. Choose an offer from the list and click “Accept Offer.”
4. Click “Create Link.” A unique link tied to your ID will be generated. Share it across your channels—now the specified percentage from each purchase made by your referrals for that creator will go to you.
5. Payments are made twice a month when the minimum amount is reached (€100, ₽3,000, or 100 USDT):
* On the 10th (or the next business day) of each month for payments received from the 16th to the 31st of the previous month.
* On the 25th (or the next business day) of each month for payments received from the 1st to the 15th of the current month.
{% hint style="info" %}
**You can also find an offer in your favourite creator’s channel and follow the same steps starting from step 3**
{% endhint %}
Got more questions?
**Does the partner also pay the service commission?**\
No, the commission is paid only by the creator. The remaining amount is split between the creator and the partner according to the terms of the offer.
**What does the "reward period" mean?**\
It’s the period during which the partner will earn revenue. This duration can vary for each partner. For example, if you set the offer duration to six months, and a user makes a purchase through the referral link, the partner will receive % from all purchases made by that user for the next six months.
**What is the best way to promote my referral offer?**\
Share your referral offer on social media and provide a detailed description of the product and some info about yourself — who you are and what you do. It's also a good idea to explain the mechanics: what will the partner earn and what technical steps they need to take. This will motivate partners to join your offer.
**Am I sharing revenue only from the user brought by the partner, or all revenue?**\
You share only the revenue from purchases made by the user the partner brought in. This users are called referrals.
**If I stop or archive the offer, will partners who have already accepted it still receive income for the offer's duration?**\
Yes, but new partners won’t be able to join.
**Sould I explain what the partner gets in the offer's description, or it's the same as what's written in the subscription/digital products?**\
Provide a detailed description of your product. The partner will see this text, so you should explain what you’re offering to subscribers. This will motivate partners to promote your offer more effectively.
**Does the partner need to verify their identity to withdraw funds?**\
Yes, to participate in the Tribute affiliate program, a partner needs to go through [verification process.](https://wiki.tribute.tg/faq)
**Does both the partner and the referral need to be subscribers of the creator?**\
The partner does not need to be a subscriber of the creator.
**If I raise the subscription price, will partners earn more too, or I'll need to set up the new agreement?**\
Partners earn a fixed percentage of your revenue, so their earnings will increase with the new price.
**If someone subscribes through a partner and renews the subscription for the next month, does the partner get a percentage for the renewal? Or do they only earn from the first subscription?**\
It depends on the offer’s duration. If it lasts longer than a month, commissions are applied.
# FAQ
**Does the partner also pay the service commission?**\
No, the commission is paid only by the creator. The remaining amount is split between the creator and the partner according to the terms of the offer.
**What does the "reward perod" mean?**\
It’s the period during which the partner will earn revenue. This duration can vary for each partner. For example, if you set the offer duration to six months, and a user makes a purchase through the referral link, the partner will receive % from all purchases made by that user for the next six months.
**What is the best way to promote my referral offer?**\
Share your referral offer on social media and provide a detailed description of the product and some info about yourself—who you are and what you do. It's also a good idea to explain the mechanics: what will the partner earn and what technical steps they need to take. This will motivate partners to join your offer.
**Am I sharing revenue only from the user brought by the partner, or all revenue?**\
You share only the revenue from purchases made by the user the partner brought in.
**If I stop or archive the offer, will partners who have already accepted it still receive income for the offer's duration?**\
Yes, but new partners won’t be able to join.
**Sould I explain what the partner gets in the offer's description, or it's the same as what's written in the subscription/CTAs?**\
Provide a detailed description of your product. The partner will see this text, so you should explain what you’re offering to subscribers. This will motivate partners to promote your offer more effectively.
**Does the partner need to verify their identity to withdraw funds?**\
Yes.
**Does both the partner and the referral need to be subscribers of the author?**\
The partner does not need to be a subscriber of the author.
**If I raise the subscription price, will partners earn more too, or I'll need to set up the new agreement?**\
Partners earn a fixed percentage of your revenue, so their earnings will increase with the new price.
**If someone subscribes through a partner and renews the subscription for the next month, does the partner get a percentage for the renewal? Or do they only earn from the first subscription?**\
It depends on the offer’s duration. If it lasts longer than a month, commissions are applied.
# How to connect the bot
1. Open Telegram on any device and search for the bot **@Tribute**. Activate the bot with the «Start» button.
2. Click «Start Monetization».
3. Pass verification by following the on-screen instructions.
4. Wait for our message with the verification results. This can take anywhere from a few minutes to an hour.
3. Add the **@Tribute** bot with admin rights to the channel. Give the bot the rights to send, edit and delete messages, as well as generate invite links. The bot will not send or delete messages in the channel without your permission.
3. The **Tribute** bot will check your channel for basic requirements. You can add the bot to more than one of your channels.
4. Complete your payment details, select your country and how you want to receive payments.
# Adding bot to a channel
## iPhone (iOS)
1. Copy the name of the bot — **@Tribute**.
2. Open the settings of the channel you want to add the bot to.
3. Select «Administrators».
4. Click «Add Admin».
5. In the search, type the name of the bot **@Tribute**. Make sure the bot has a blue verification checkmark and select it.
6. Grant the bot the following permissions: Send messages, Edit messages, Delete messages, Add subscribers. Click «Done».
## Android
1. Open the settings of the channel to which you want to add a bot.
2. Select «Administrators».
3. Click «Add Admin».
4. In the search, type the name of the bot **@Tribute**.
5. Grant the bot the following permissions: Send messages, Edit messages, Delete messages, Add subscribers. Click «Done».
# Fees, limits, currencies
### F**ee:**
* **10%** (from each successful transaction, this includes fees of the service and payment providers).
Additional fees may be charged by your bank when withdrawing funds (fees for incoming transactions, exceeding of limits, currency exchange differences, etc.). For more details, please contact your bank's support.
### Buyer's fee
For subscribers, a dynamic service fee applies to every payment — including subscriptions, donations, digital products. The commission percentage depends on the payment amount: the higher the purchase amount, the lower the fee.
This rule applies to all payments except transactions made via Telegram Wallet and purchases of physical goods.
Contact @TributeCreatorBot to learn more.
### **Supported currencies:**
Currently, we support payouts in rubles and euros, but other currencies will be available soon.
Additionally, we support payment acceptance in TON, USDT, BTC, and cryptocurrency payouts through [@wallet](https://t.me/wallet).
### **Limitations on payment amount:**
#### Subscription, donation, goal, **custom digital product**:
* **€1, $1** or **₽100** is the minimum one-time transaction.
* **€3,000, $3,000** or **₽300,000** is the maximum single transaction.
#### Digital product:
* **€1, $1** or **₽100** is the minimum one-time transaction.
* **€1,000, $1,000** or **₽100,000** is the maximum single transaction.
# Payouts
The funds you earn through Tribute can be withdrawn once you reach the minimum payout threshold. Cryptocurrency can be withdrawn to the @wallet crypto wallet, while rubles and euros can be withdrawn either to a bank card or to the @wallet crypto wallet.
### Minimum payout threshold
{% hint style="info" %}
**The minimum payout threshold in Tribute is 3,000 ₽, 100 €, or 100 USDT.**
{% endhint %}
### There are two ways to receive payouts in Tribute:
1. Automatic Payouts
2. On-Demand Payouts 🆕
### 1. Automatic Payouts (Scheduled)
Once the[ minimum payout threshold](#minimum-payout-threshold) is reached, funds are automatically transferred twice a month:
\* On the 25th (or the next business day) — for earnings from the 1st to the 15th of the current month;
\* On the 10th (or the next business day) — for earnings from the 16th to the 31st of the previous month.
The processing time for funds depends on your country and the chosen payout method — it can take from a few days to up to a month.
{% hint style="info" %}
If the [minimum payout threshold ](#minimum-payout-threshold)is not reached during a given period, the funds will accumulate and become available for withdrawal on the next scheduled payout date once the threshold is met.
{% endhint %}
### On-Demand Payouts
Now, once you reach the [minimum payout threshold](#minimum-payout-threshold), a "Request Payout" button will appear in your Creator Dashboard under the payouts section. You can then submit a manual payout request.
This method allows you to receive your earnings twice as fast:
\* From the 16th of the month — for earnings from the 1st to the 15th
\* From the 1st of the month — for earnings from the 16th to the 31st of the previous month
{% hint style="info" %}
You can submit a maximum of two payout requests per month.
{% endhint %}
### How to request a payout:
1\. **Click "Request Payout"**
2\. **Choose your withdrawal method**
Select your preferred payment method and click "Withdraw"
3\. **Done!**
Your funds will arrive within 2 to 5 business days.
{% hint style="warning" %}
Once you switch to on-demand payouts, automatic payouts will stop.
{% endhint %}
You can switch between automatic and on-demand payout methods at any time.
\
\
# Payout balance
**The payout balance** is the money accumulated during the billing period, after deducting the service fee. This money will be paidout on the next payout date if you have reached the minimum payout threshold. If the amount is less, the money will continue to accumulate and will be transferred to you on the next payout date when the minimum threshold is reached.
# Your earnings and Settlement
**Your earnings** are the amount you receive in billing periods from subscriptions and donations minus payouts.
**Settlement** is the total amount we transfer to your card or bank account.
# Bank fees
Your bank and correspondent banks may charge additional fees when transferring payouts to you. These may be related to limits on the amount, the ability to process a payment in a certain currency, the bank's internal policy, etc. The final amount credited to your account may be slightly different from the expected amount. If the difference is significant, it may be due to currency conversion.
# Currencies and conversion fees
You can select a currency when creating a subscription. You can create multiple subscriptions in different currencies, each of which will create a balance in the appropriate currency.
The subscription currency you choose will be reflected in the conversion fees of the payments you are charged and the payouts you receive.
**How to avoid conversion losses:**
* Create subscriptions and donations in the currencies that your subscribers primarily use.
* Choose to receive payouts in the currency of your subscriptions or donations.
**Example:**
1. €100 paid with a European bank card in euros. No fees.
2. €100 transferred to your European bank account in Euros. No fees.
3. €100 paid with a US bank card in US dollars. Your subscriber will pay a fee according to the rate of the bank that issued the card.
4. €100 transferred to your US bank account in euros. You will pay the fee according to your bank's rate.
# New requirements for payout details
From January 22, 2025, payment providers require that you include your **address and city** in your payment details in these countries:
**Austria**
**Belgium**
**Cyprus**
**Czech Republic**
**Estonia**
**France**
**Germany**
**Hungary**
**Ireland**
**Latvia**
**Lithuania**
**Netherlands**
**Poland**
**Portugal**
**Romania**
**Slovakia**
**Spain**
**Sweden**
For correct payouts in these countries, please add the city and address to the payout information.
# Donations
**Donations** are a form of gratuitous support from your subscribers thanking you for the content you publish. You can collect donations in your Telegram channels. Donations are not for the purchase of any content, service or product. Your subscribers can choose any amount of donations, but not above the limits.
# How to create a donation
1. Open the Creator Dashboard
2. Click Donations
3. Select Create Donation
4. Fill in the fields: Title, Description, Text, add a cover, then click Continue
5. Set the currency and frequency of payments
6. Click Create
# Regular donations
**Regular donations** are donations of an amount chosen by the subscriber with a specified frequency. For example, once a week, once a month or once a year.
**What are they for?**
We added this feature so that subscribers can regularly support authors with a comfortable amount of money.
**What’s different from subscriptions?**
1. This feature is available for public channels, like other donations.
2. The amount of payment is determined not by the author, but by the subscriber.
**How to connect regular donations?**
No additional actions are required from the creator. If you have already connected donations, then when choosing an amount, the subscribers will now be able to choose whether they want to make a one-time donation or regularly donate a certain amount.
\
\
\
# How to connect donations to OBS
Learn what recurring donations are and how to connect them in Tribute. 💵 Accept payments in a convenient currency through Tribute, with responsive support, low fees, and maximum convenience
The OBS integration displays donations right on your stream. Tribute generates a personal OBS link — you only need to add it once.
The OBS integration is in the **Donations and Goals** section of the creator profile — in the **Integrations** block.
**How it works**
The donations widget is a page that you add to OBS as a Browser Source. When a subscriber sends a [donation](https://wiki.tribute.tg/for-content-creators/donations), an alert appears over the stream with the sender’s name, amount, and message. The link is personal and permanent: add it once. No separate setup is required — alerts work with your current donations.
**How to connect**
1\. Open the creator profile in the [Tribute bot](https://t.me/tribute).
2\. Select the **Donations and Goals** section
3. In the **Integrations** block, open **OBS Integration**.
4. Scroll to the bottom of the screen and click **Copy link for OBS** — your personal link will be copied to the clipboard.
5. Open OBS Studio. In the **Sources** block, click **+** and add a **Browser** source.
6. In the source creation window, enter any name, such as Tribute, and click **OK**.
7. In the source properties, clear the **URL** field, paste the link from the clipboard, and click **OK**.
8. Return to Tribute and click **Send test donation**.
9. If everything is connected correctly, a test alert with the name and amount will appear in OBS. Drag it to the right place on the screen.
A test donation shows how the alert will look on stream before you receive real support. Send it as many times as needed to adjust the widget size and position in OBS.
# Goals
**Goals is** a new feature that allows you to set specific donation targets. Simply come up with a goal and share it with your subscribers. For example, a musician can raise donations for a new album release, and an artist can fund a graphics tablet to create more artwork.
# How to Create a Donation Goal
1. Open "Goals" in the creator's dashboard.
2. Select "Create Goal."
3. Fill in all the necessary details: title, description, button text, and upload a cover image if needed.
4. Click "Continue."
5. Select the currency and set the goal amount, taking the fee into account.
6. Click "Create."
# Info Products and Content
Info products and content are unique pieces of content that you can sell. It can be text, a photo, video, audio, location or an attached file (JPEG, PNG, MP4, PDF, TXT, MP3, WAV, WAVE, SVG). Essentially, anything that can be sent on Telegram.
Payments can be accepted via card (in rubles, US dollars, and euros), as well as via Telegram Stars (in this case, payouts for sold items are credited to the creator in USDT to their Telegram Wallet).
# How to Create a Digital Product
1. Send your digital product as a single message to the @Tribute bot chat. This can be text, a photo, video, audio, location or an attached file (JPEG, PNG, MP4, PDF, TXT, MP3, WAV, WAVE, SVG).
2. In the bot's response message, click "Create Digital Product."
3. Select the currency, set the price, add a title, and describe your product, highlighting its key benefits and value. Create text for the button and upload a cover image for the product if necessary.
4. Click "Create."
5. Done! Your product is created and ready for sharing.
# How to Share a Digital Product
1. Type @Tribute in any channel or group in Telegram.
2. Select the digital product you want to share in the pop-up.
{% hint style="info" %}
You can also copy the link to your digital product from your content creator profile and share it anywhere you like.
{% endhint %}
### What happens next
When a subscriber purchases your product, it will be available in the chat with the @Tribute bot and their subscriber profile. If you decide to delete the product, access will remain for users who have already purchased it, but new sales will be impossible.
# How to Edit a Digital Product
1. Open the digital product in your creator dashboard.
2. Click on "More" and select "Edit".
3. Update the necessary information.
4. Click "Save."
# How to Delete a Digital Product
1. Open the digital product in your creator dashboard.
2. Click on "More" and choose "Delete".
3. Confirm the action.
{% hint style="info" %}
After deletion, the product will remain accessible to users who have already purchased it, but new sales will be impossible.
{% endhint %}
# How to Create a Digital Custom Product
**A custom digital product is** a unique piece of content you create upon a subscriber's request. This can be a personalized text or video greeting, a unique photo, audio, or a file. Almost anything that can be sent in a Telegram message.
Selling digital custom products is possible in rubles, euros, or cryptocurrency through the [Wallet in Telegram](https://wiki.tribute.tg/for-content-creators/wallet-pay).
## How to сreate
1. Open the "Menu" in the @Tribute bot.
2. In your Creator Dashboard, select "Digital Products."
3. Choose "Custom."
4. Click "Create Custom Product."
5. Select the payment method — bank card for subscriptions in rubles and euros, Wallet for cryptocurrency payments.
6. Choose the currency and set the price.
7. Then, add a title and describe your product, highlighting its key benefits and value. Craft text for the button and upload a cover image if needed.
8. Click "Create."
9. Publish the product following [the instructions](https://wiki.tribute.tg/for-content-creators/what-is-a-digital-product/how-to-share-a-digital-product) so your subscribers can order it.
## How to fulfill an order
When you receive a notification about an order for your custom product, you need to fulfill it.
**Here's how:**
1. Click on the notification about the custom order in the @Tribute bot.
2. Click "Reply."
3. Click "Attach" and add a file. It can be text, photo, video, audio, location, or an attached file (JPEG, PNG, MP4, PDF, TXT, MP3, WAV, WAVE, SVG). You can send almost anything in a Telegram message.
4. In the bot's reply message, click "Send Product."
5. After Tribute successfully moderates the product, it will be sent to your customer. You'll receive a notification once the order is fulfilled and you will receive payment for the product.
6. If your product does not pass moderation, you can resubmit it.
# How to set up web payment for digital products
We have added an alternative payment method via the links in the bro. Now your subscribers can pay for your digital products not only with “Stars” on Telegram, but also with a bank card via a web link.
## **How to add a web payment option:**
1. Go to the instant product sсreen and click “Links”.
2. Copy the contents of the “Web link” field.
3. Share this link on any of your platforms – for example, on YouTube.
4. Done! Now, your subscribers can pay for your digital product with a card via the link in the browser and receive it in the @tribute Telegram bot.
# Integrating Digital Products into Your Product
This guide is for Telegram bot and service owners who want to use Tribute as a payment system. Accept payments via SBP and Telegram Stars, receive withdrawals in USDT without complex payment provider
### Benefits of Tribute Digital Products Integration
#### For you as a service owner:
* **Payment acceptance** - SBP and Telegram Stars
* **Simple integration** - create a product, get a link, set up a webhook
* **Ready infrastructure** - no need to integrate payment providers yourself
* **Automatic withdrawals** - receive money in USDT
#### For your users:
* **Convenient payment** - one-click purchase through Telegram
* **Available payment methods** - SBP, Telegram Stars
### How it works: general scheme
#### 1. You [create a digital product](https://wiki.tribute.tg/en/for-content-creators/digital-product/how-to-create-a-digital-product) in Tribute
For example, for an AI assistant it could be "AI Assistant Access for 1 month"
#### 2. Get a unique payment link
Each product has its own link in the format:
* For Telegram: `https://telegram.me/tribute/app?startapp=p123`
* For browser: `https://web.tribute.tg/p/123`
#### 3. Direct users to this link
In your bot or other service, add a "Pay" button that leads to the product link
#### 4. User pays
The buyer can:
* Pay directly with Telegram Stars (if available on balance)
* Buy Stars via SBP and immediately exchange them for the product
#### 5. You receive a webhook about successful payment
After payment, a POST request with purchase information arrives at your server. More about webhook format in the [webhooks documentation](https://wiki.tribute.tg/for-content-creators/api-documentation/webhooks#newdigitalproduct)
#### 6. Provide access to the user
Activate the service for the user using the Telegram ID from the webhook
### Step-by-step setup instructions
#### Step 1: Registration in Tribute
1. Open [@tribute](https://telegram.me/tribute) in Telegram
2. Click "Start" and follow the instructions
3. Go to the "Author Dashboard" section
#### Step 2: Creating a digital product
1. **In the dashboard, select "Digital Products" → "Create instant product"**
2. **You will be redirected to the bot chat**
Send the bot a message that will become your digital product. This can be any message - for example, a photo with description, video, file, or even a voice note.
**Example text message for integration:**
```
✅ Thank you for purchasing AI Assistant access for 1 month!
Access will be provided automatically.
To activate your subscription, return to @YourAIBot
```
> **Important:** This is the exact message the buyer will receive after payment. Add instructions for the user so they understand what to do next. Once the product is created, this message cannot be edited (but you can always create a new digital product with a different message).
3. **After sending the message, click the "Create Product" button from the bot's message**
4. **Fill in the required fields:**
* **Currency** - choose the payment currency
* **Name** - what the buyer will see (for example: "AI Assistant for 1 month")
* **Description** - brief product description
* **Price** - cost in the selected currency
5. **Save the product**
After saving, you will receive a unique payment link that can be used in your integration
#### Step 3: Getting API key
1. In the dashboard, open the menu (three dots) → "Settings"
2. Go to the "API Keys" section
3. Click "Generate New Key"
4. Save the key in a safe place - you'll need it to verify webhooks
#### Step 4: Setting up webhooks
1. In the "API Keys" section, find the "Webhook URL" field
2. Specify your server address for receiving webhooks:
```
https://your-server.com/webhook/tribute
```
3. Save settings
#### Step 5: Processing webhooks on your server
After successful payment for a digital product, Tribute will send a POST request to your URL:
Webhook format
```json
{
"name": "new_digital_product",
"created_at": "2025-03-20T01:15:58.332Z",
"sent_at": "2025-03-20T01:15:58.542Z",
"payload": {
"product_id": 456,
"amount": 500,
"currency": "usd",
"user_id": 31326,
"telegram_user_id": 12321321
}
}
```
**Webhook signature verification**
Each request contains a `trbt-signature` header with HMAC-SHA256 signature of the request body. Examples of signature verification and webhook processing are available in the [webhooks documentation](https://wiki.tribute.tg/for-content-creators/api-documentation/webhooks)
#### Step 6: Integration into your bot
In your Telegram bot, add a payment button
Python code
```python
# Python + python-telegram-bot
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
def send_payment_button(update, context):
keyboard = [[
InlineKeyboardButton(
"💳 Pay ($9.99)",
url="https://telegram.me/tribute/app?startapp=p456"
)
]]
reply_markup = InlineKeyboardMarkup(keyboard)
update.message.reply_text(
"AI Assistant for 1 month - $9.99",
reply_markup=reply_markup
)
```
### Working with API
## 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"}}}}}}}}}
```
## 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"}}}}}}}}}
```
## 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"}}}}}}}}}
```
{% openapi-webhook spec="api-en" name="newDigitalProduct" method="post" %}
[api-en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="api-en" name="digitalProductRefund" method="post" %}
[api-en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
### Creating different tariffs
For different tiers, create several digital products:
1. **AI Assistant - 1 month** (ID: 456) - $9.99
2. **AI Assistant - 3 months** (ID: 457) - $24.99
3. **AI Assistant - 1 year** (ID: 458) - $79.99
### Handling retry attempts
When webhook delivery fails, Tribute retries after:
* 5 minutes
* 15 minutes
* 30 minutes
* 1 hour
* 10 hours
Make sure your handler is idempotent (reprocessing the same payment won't create duplicates).
### Withdrawals
You can withdraw earned funds in USDT (bank card withdrawals will be added in the future). Set up automatic withdrawals in the "Wallet" section.
### Frequently Asked Questions
How quickly do webhooks arrive?
Usually within 1-2 seconds after successful payment.
Can I cancel a payment?
Digital products can be canceled through Tribute support.
***
# Statistics
In the creator's dashboard, there's a section with data on earnings and subscribers. Data can be sorted for individual channels and groups or all you manage. Statistics are updated every 15 minutes and displayed according to the UTC zone.
# Available data
**Earnings**: This includes information on sold subscriptions and received donations. Statistics are available for the entire period or for a selected time frame. There's also a breakdown by currency.
**Subscriptions**: You can view the new, renewed, and canceled subscriptions. A separate section contains information on active subscribers.
# Where to find it
1. Open the Tribute bot on any device.
2. Click "Menu".
3. In the creator's dashboard, under the earnings data, select "Statistics."
4. Choose the data source: "General" or a specific channel or group. Click "Done".
# How to set up access to comments
You can grant subscription access to your channel and a comment group. If you don't have such a group, you should create one.
### How to create a comment group
1. Open your subscription channel and tap its name.
2. Select "Edit" at the top.
3. Choose "Discussion" and add a group chat.
### How to set up a comment group
* [iOS](/for-content-creators/how-to-set-up-access-to-comments/how-to-set-up-a-comment-group-ios)
* [Android](/for-content-creators/how-to-set-up-access-to-comments/how-to-set-up-a-comment-group-android)
### How to set up paid access to a group
1. Open the "Menu" in the @Tribute bot.
2. In the "Channels and Groups" section, select the channel where you want to enable comments.
3. Choose the subscription you want to configure for comment access.
4. Tap "Comment Access" inside the subscription and check the box. Tap "Save."
# How to set up a comment group (iOS)
1. Open your comment group and tap its name.
2. Select "Edit" at the top.
3. Tap on "Group Type."
4. Set the "Group Type" to "Private."
5. Under "Who can send messages," select "Only members."
6. Enable "Approve new members" and tap "Done."
7. Add the @Tribute bot as an admin in this group. Make sure it can delete, pin messages, block, and add users.
Your group is now under review. Tap "Back" and wait for the moderation process to complete. Once you receive confirmation from the bot about successful moderation, proceed to the "How to set up paid access to a group" instructions.
# How to set up a comment group (Android)
1. Open your comment group and tap its name.
2. Tap the edit icon at the top.
3. Tap on "Group Type."
4. Set the "Group Type" to "Private."
5. Go back and select "Linked Channel."
6. Enable "Only members" and "Approve new members."
7. Add the @Tribute bot as an admin in this group. Make sure it can delete, pin messages, block, and add users.
Your group is now under review. Tap "Back" and wait for the moderation process to complete. Once you receive confirmation from the bot about successful moderation, proceed to the "How to set up paid access to a group" instructions.
# API Documentation
## Authorization
To access the Tribute API, you need to obtain an API key through the author dashboard.
### How to get an API key
1. **Open Author Dashboard**: Go to your Tribute author dashboard
2. **Navigate to Settings**: Click on the three dots (⋯) menu
3. **Go to API Keys**: Select "API Keys" from the settings menu
4. **Generate New Key**: Click "Generate API Key" button
5. **Copy and Save**: Copy the generated key and store it securely
### Using the API key
The API key is used in the `Api-Key` header in every HTTPS request to the API.
#### Example with curl:
```bash
curl -X GET \
'https://tribute.tg/api/v1/products' \
-H 'Api-Key: your_api_key_here'
```
# Orders
Order operations
## Get Orders List
> Returns a list of physical orders for the current user with pagination
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order operations"}],"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":{"Order":{"type":"object","required":["id","status","created","fullName","email","phone","telegramID","address","locality","fullAddress","customerNote","items","deliveryCost","currency"],"properties":{"id":{"type":"integer","description":"Unique order identifier"},"status":{"type":"string","description":"Order status","enum":["pending","shipped","delivered","canceled","refunded"]},"created":{"type":"string","format":"date-time","description":"Order creation date and time"},"fullName":{"type":"string","description":"Recipient full name"},"email":{"type":"string","format":"email","description":"Recipient email"},"phone":{"type":"string","description":"Recipient phone"},"telegramID":{"type":"integer","format":"int64","description":"Buyer's Telegram ID"},"address":{"type":"object","description":"Delivery address","properties":{"countryIso2":{"type":"string","description":"Two-letter ISO country code"},"countryIso3":{"type":"string","description":"Three-letter ISO country code"}}},"locality":{"type":"string","description":"City"},"fullAddress":{"type":"string","description":"Full delivery address"},"customerNote":{"type":"string","description":"Customer note"},"items":{"type":"array","description":"Order items","items":{"$ref":"#/components/schemas/OrderItem"}},"deliveryCost":{"type":"number","format":"float","description":"Delivery cost"},"currency":{"type":"string","description":"Order currency"}}},"OrderItem":{"type":"object","required":["id","price","quantity","currency","name","attributes"],"properties":{"id":{"type":"integer","description":"Product variant ID"},"price":{"type":"number","format":"float","description":"Unit price"},"quantity":{"type":"integer","format":"int64","description":"Quantity"},"currency":{"type":"string","description":"Currency"},"name":{"type":"string","description":"Product name"},"attributes":{"type":"object","description":"Product attributes (size, color, etc.)","additionalProperties":{"type":"string"}}}},"Meta":{"type":"object","required":["total","offset","limit"],"properties":{"total":{"type":"integer","format":"int64","description":"Total number of records"},"offset":{"type":"integer","format":"int64","description":"Page number"},"limit":{"type":"integer","format":"int64","description":"Number of records per page"}}},"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":{"/physical/orders":{"get":{"summary":"Get Orders List","description":"Returns a list of physical orders for the current user with pagination","tags":["Orders"],"parameters":[{"name":"lastOrderId","in":"query","description":"ID of the last order for cursor pagination","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Filter by order status (multiple values allowed)","required":false,"schema":{"type":"array","items":{"type":"string","enum":["pending","shipped","delivered","canceled","refunded"]}},"style":"form","explode":true},{"name":"limit","in":"query","description":"Number of records per page (maximum 50)","required":false,"schema":{"type":"integer","default":50,"maximum":50}},{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","default":1}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/Order"}},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"description":"Bad request (invalid status)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Order Details
> Returns detailed information about a specific order
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Orders","description":"Order operations"}],"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":{"Order":{"type":"object","required":["id","status","created","fullName","email","phone","telegramID","address","locality","fullAddress","customerNote","items","deliveryCost","currency"],"properties":{"id":{"type":"integer","description":"Unique order identifier"},"status":{"type":"string","description":"Order status","enum":["pending","shipped","delivered","canceled","refunded"]},"created":{"type":"string","format":"date-time","description":"Order creation date and time"},"fullName":{"type":"string","description":"Recipient full name"},"email":{"type":"string","format":"email","description":"Recipient email"},"phone":{"type":"string","description":"Recipient phone"},"telegramID":{"type":"integer","format":"int64","description":"Buyer's Telegram ID"},"address":{"type":"object","description":"Delivery address","properties":{"countryIso2":{"type":"string","description":"Two-letter ISO country code"},"countryIso3":{"type":"string","description":"Three-letter ISO country code"}}},"locality":{"type":"string","description":"City"},"fullAddress":{"type":"string","description":"Full delivery address"},"customerNote":{"type":"string","description":"Customer note"},"items":{"type":"array","description":"Order items","items":{"$ref":"#/components/schemas/OrderItem"}},"deliveryCost":{"type":"number","format":"float","description":"Delivery cost"},"currency":{"type":"string","description":"Order currency"}}},"OrderItem":{"type":"object","required":["id","price","quantity","currency","name","attributes"],"properties":{"id":{"type":"integer","description":"Product variant ID"},"price":{"type":"number","format":"float","description":"Unit price"},"quantity":{"type":"integer","format":"int64","description":"Quantity"},"currency":{"type":"string","description":"Currency"},"name":{"type":"string","description":"Product name"},"attributes":{"type":"object","description":"Product attributes (size, color, etc.)","additionalProperties":{"type":"string"}}}},"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":{"/physical/orders/{id}":{"get":{"summary":"Get Order Details","description":"Returns detailed information about a specific order","tags":["Orders"],"parameters":[{"name":"id","in":"path","description":"Order ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Bad request (order ID not provided)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Subscriptions
Subscription catalog with pricing periods
## Get Subscriptions List
> Returns the authenticated user's subscriptions, each with its pricing periods
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Subscriptions","description":"Subscription catalog with pricing periods"}],"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":{"Subscription":{"type":"object","required":["subscriptionId","name","currency","periods"],"properties":{"subscriptionId":{"type":"integer","description":"Subscription ID"},"name":{"type":"string","description":"Subscription name"},"currency":{"type":"string","description":"Currency code"},"periods":{"type":"array","description":"Pricing periods","items":{"$ref":"#/components/schemas/SubscriptionPeriod"}}}},"SubscriptionPeriod":{"type":"object","required":["periodId","period","price"],"properties":{"periodId":{"type":"integer","description":"Period ID"},"period":{"type":"string","description":"Billing period","enum":["trial","onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"price":{"type":"number","description":"Price in major currency units"}}},"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":{"/subscriptions":{"get":{"summary":"Get Subscriptions List","description":"Returns the authenticated user's subscriptions, each with its pricing periods","tags":["Subscriptions"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"result":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}}}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many requests (rate limit exceeded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# 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"}}}}}}}}}
```
# Webhooks
Webhooks for system event notifications.
**Setup:**
1. Go to Creator Dashboard → Settings (three-dot menu) → API Keys section
2. Generate API key if you haven't already
3. Specify your webhook URL in the webhook settings
**Signature verification:** Each request contains `trbt-signature` header with HMAC-SHA256 signature of request body signed with your API key.
**Retry attempts:** On delivery failure, system retries with exponential backoff over \~24 hours: 5min, 15min, 30min, 1h, 2h, 4h, 8h, 8h.
**Subscription type (payload.type) in subscription events:**
* `regular` — regular paid subscription (new subscription or renewal)
* `gift` — gift subscription (gift purchase)
* `trial` — trial subscription (trial activation)
**Type transitions:** When a `gift` or `trial` subscription renews, the next subscription becomes `regular`, reflected in the `renewed_subscription` event.
{% openapi-webhook spec="en" name="newSubscription" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="cancelledSubscription" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="renewedSubscription" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="physicalOrderCreated" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="physicalOrderShipped" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="physicalOrderCanceled" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="newDonation" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="recurrentDonation" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="cancelledDonation" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="newDigitalProduct" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="en" name="digitalProductRefund" method="post" %}
[en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
# Wallet Pay
You can now accept payments for subscriptions and donations through @[wallet](https://t.me/wallet).
**How it works:**
1\. In your channel's subscription settings, add Wallet Pay as a payment method. Alternatively, you can choose it as the only method.
2\. Set the subscription prices in USD, EUR, or RUB. Or just in EUR and RUB, if you have selected both "Bank Card" and Wallet Pay as payment methods.
3\. Subscribers pay for donations and subscriptions using cryptocurrencies like TON, USDT, or BTC at the current exchange rate.
4\. After payment, the subscription or donation amount is immediately converted into USDT. It is then transferred twice a month to your [Wallet](https://t.me/wallet), provided the total reaches the minimum of 100 USDT.
5\. You can exchange USDT for another cryptocurrency, transfer it to another crypto wallet, or sell it directly in the [Wallet](https://t.me/wallet) through the P2P Market.
Learn more about selling on the P2P Market via the [link](https://wallet.helpscoutdocs.com/article/5-p2p-market-faq).
#### Limitations on a payment amount:
**Subscriptions:**
* €1 is the minimum one-time transaction.
* €1 000 is the maximum single transaction.
**Donate:**
* €1 is the minimum one-time transaction.
* €2,000 is the maximum single transaction.
# Telegram Stars
Tribute has launched payments with Telegram's in-app currency — [Telegram Stars](https://telegram.org/blog/telegram-stars/ru?setln=en). Paying for digital products with Stars is simple and seamless. Customers can purchase Stars directly within the Telegram app, without needing to leave the platform.
**This means that digital products in Tribute can only be purchased with Telegram Stars.**
## How to buy digital products with Stars?
To buy digital products with Stars, simply use the Tribute bot. Select your product, choose the amount of Stars to purchase, and complete the transaction.
Purchase Stars via in-app purchases on the App Store or Google Play for smartphones, or use a bank card with the desktop version of Telegram or through [@PremiumBot](https://telegram.me/premiumbot).
## In what currency can you sell digital products?
You can list in Euros, but the payout for sold products will be in USDT.
Here's how it works:
1. The creator lists a digital product on Tribute with a price in Euros.
2. Tribute converts the price to Stars based on Telegram’s exchange rate.
3. Users buy the product using Stars.
4. Tribute exchanges Stars for USDT at [Telegram’s rate](https://telegram.org/tos/bot-developers#6-2-4-rewards-for-stars).
5. Payouts in USDT are made to your @wallet twice a month, after the minimum payout threshold is reached.
{% hint style="info" %}
*Payouts for digital products purchased in Euros or cryptocurrency before 12 June 2024 will be sent to creators' bank cards or @wallets as before.*
{% endhint %}
\
How to set a price in Stars?
----------------------------
\
Now you can set a fixed price for digital products in Stars. This way, your subscribers no longer need to purchase multiple packs of internal currency or worry about complicated currency conversions.
You can also set a price in Stars for existing digital products. Here are 3 easy steps :
1. Go to the digital products screen and click "More".
2. Set your desired price in "Stars”.
3. Save the changes.
Done! Now your subscribers can easily pay using "Stars".
## What is the exchange rate for Stars?
The purchase rate for Stars varies based on the user’s location, with Telegram automatically setting the rates according to the local currency.
For creators, the exchange rate of Stars is set by [Telegram](https://telegram.org/tos/bot-developers#6-2-4-rewards-for-stars). Creators set prices in Euros and receive payments in USDT to their @wallet.
## Does the payout amount depend on how Stars are purchased?
No matter how Stars are purchased — whether via in-app purchases on the App Store or Google Play, or with a bank card — creators receive the full amount minus Tribute’s standard 10% commission.
## Are subscriptions and donations also paid with Stars?
Currently, Telegram Stars are only used for purchasing digital products. We will notify you through the official [Tribute channel](https://telegram.me/TributeNewsEN) if this changes.
\
# Content Restrictions
All content creators using the Tribute service must adhere to specific rules and refrain from publishing prohibited content.
**Prohibited Content Includes**
#### 1. **Impersonation**
* Content published with the intent to impersonate an individual, group of individuals, or organizations.
* The use of alternative names for people and organizations is permitted if not intended to mislead others.
#### 2. **False information and misrepresentation**
* Dangerous content containing false or misleading claims about health or medical information.
* Content with false or misleading statements regarding civil processes.
* Distortion of information or deliberate omission of facts intended to defraud.
* Content that deceptively prompts users to disclose personal information or creates opportunities for phishing and baiting.
#### 3. **Content featuring minors or unverified individuals**
* Any portrayal of individuals under 18 years old (or content indirectly implying the participation of minors), including mentions or implications of infants, newborns, or children in any context.
* Documentation must confirm that all individuals featured or mentioned in your content are at least 18 years old, with written consent from each for the use of the content. (Note: We require documentation for all participants, even those in the background or voice-only contributors).
#### 4. Discrimination
* Content containing offensive statements or expressions of hate directed or based on race, skin color, sex, religion, gender, disability, nationality, or other marginalized or disadvantaged groups.
* Content that dehumanizes, belittles, or negatively portrays certain protected categories of people or their representatives based on their characteristics.
#### 5. Personal data
* Content containing another person's personal data published without consent, such as full names, faces in photos or videos, and other information disclosed without consent.
* Information that allows personal identification and other personal data about you or others, including financial or medical details.
#### 6. Sexual or adult content
* Unwanted sexual content or content that sexually objectifies another user or anyone else without consent or contains fake or manipulated sexual content regarding another user or anyone else (including "deepfakes").
* Escort services, human trafficking for sexual exploitation, or prostitution.
* Content depicting rape or forced sex, whether real or simulated.
* Sexual exploitation of children and the portrayal of minors in a sexual context.
* Acts of bestiality or explicit scenes involving animals.
* Scenes depicting necrophilia.
* Acts of incest.
#### 7. Nudity in public places
* Any content filmed or broadcast from places where public nudity is prohibited by law.
* Any content filmed or broadcast from a location without permission or consent from the location owner, such as public stores, parks, gyms, or rented spaces.
#### 8. Violence and cruelty
* Scenes of violence and cruelty involving humans or animals.
* Graphic scenes of violence, including significant blood, serious injuries, or death of animals or people.
* Killing any living beings.
#### 9. Other forms of illegal or inappropriate content
* Any content demonstrating or implying the use of drugs or related paraphernalia.
* Display or use of any weapons.
* Images of vomiting, feces, urine, and blood.
* Any forms of violence or abuse, self-harm or suicide, including but not limited to cannibalism, snuff content, or promotion of violence or illegal acts.
* Content demonstrating dangerous or illegal actions, such as organ sales or human trafficking.
* Illegal goods and services: items made from endangered species, banned substances, and prescription drugs for sale on the black market.
* Materials produced by or on behalf of terrorist groups.
* Instructions for creating or preparing dangerous items.
* Content encouraging minors to engage in dangerous activities or use dangerous objects.
* Images and other materials infringing on lawful rights, including copyright, exclusive rights, or intellectual property rights, e.g., pirated software, music, videos, games, streams, etc.
* Content must not promote any forms of high-yield investments or get-rich-quick schemes.
#### **10. Content about finance, investments, and cryptocurrencies**
* Misleading or deceptive content - Any content that misleads or deliberately deceives users about financial investments, including false promises of high returns with no risk.
* Illegal financial product advertising - Sharing information about financial products and services without the necessary licensing or permissions as required by law. This includes advertising or promoting misleading Forex trading strategies.
* Insider trading - Distributing confidential information about companies to gain illegal financial advantage in the stock market.
* Market manipulation - Publishing content aimed at distorting prices for stocks, currencies, or other financial instruments.
* Financial pyramids - Promoting or participating in financial schemes designed to deceive investors.
* Unauthorized investment advice - Offering investment advice without the appropriate qualifications or licensing.
* Fraudulent cryptocurrency projects - Proposing investments in cryptocurrency projects that are fraudulent or lack a solid basis.
* Violation of international sanctions or trade restrictions - Content that breaches international sanctions or trade limitations.
# Raffle rules
Rules for a raffle among channel creators using the "Tribute" service (the "Rules")
December 11, 2024
1. **Organizer:** TRBT Limited. Registration number: HE 443898. Address: Griva Digeni, 51, ATHINEON COURT, Flat/Office 202, 8047, Paphos, Cyprus (hereinafter referred to as the "Organizer").
2. **Participants:** channel creators using the "Tribute" service for content monetization, who are 18 years of age or older.
3. **Duration:** from December 12, 2024, 00:01 (UTC +3) to January 12, 2025, 23:59 (UTC +3).
4. **Results announcement:** no later than January 20, 2025.
5. **Participation scheme:**
5.1. The number of tickets is calculated as follows:
5.1.1. The creator receives 1 ticket for every €10 or 1,000 RUB earned through Tribute during the raffle period from new paid subscriptions, donations, and the sale of digital goods.
5.1.2. The number of tickets depends on the total subscription payment amount, not the number of subscribers.
5.1.3. Physical products: The creator receives 3 tickets for every €10 or 1,000 RUB earned through Tribute during the raffle period from the sale of physical products.
5.2. For the purposes of Clause 5.1.1 of the Rules, new subscribers are considered those who have subscribed to the channel within the last two months from the start date of the draw. All types of subscriptions are taken into account
6. **Prize fund:**
* 1 x Apple Macbook Air 15" M3 2024 (16gb, 512 ssd)
* 2 x Apple iPhone 16 Pro 256GB
* 30 х Apple AirPods 4 (2024) MXP93
7. **Raffle rules**:
7.1. The prize draw will be conducted in the Organizer's official Telegram channel.
7.2. The random.org service will be used to determine the winners.
8. **Rules for receiving prizes**:
8.1. Physical delivery of prizes may not be possible in all countries and will be discussed individually.
8.2. If it is impossible to deliver a physical prize, the winner will receive the equivalent of the prize value in USDT:
* Apple Macbook Air 15" M3 2024 (16gb, 512 ssd) = 2000 USDT
* Apple iPhone 16 Pro 256GB = 1300 USDT
* 30 х Apple AirPods 4 (2024) MXP93 = 250 USDT
9. By participating in the raffle, participants give their consent to the processing of their personal data by the Organizer in accordance with the current legislation on personal data protection. Personal data processing includes collection, systematization, accumulation, storage, clarification, use, distribution, depersonalization, blocking, deletion, and destruction of data necessary for conducting the raffle and awarding prizes.
10. The right to receive a prize is personal and cannot be transferred to third parties.
11. By participating in the raffle, participants agree to the publication of their Telegram channel names, names, usernames, or IDs specifically added for the contest, which may be displayed in the interface (in full or in part), as well as the raffle results on all resources of the Organizer.
12. The Organizer reserves the right to make changes to these Rules at any time without prior notice. Such changes come into force from the moment of their publication on the Organizer's official resources. Participants are obliged to independently monitor changes in the Rules of the raffle.
13. Participation in the raffle means full agreement with these Rules.
14. The raffle is not a lottery or gambling game.
# How to pay for a subscription
{% content-ref url="/pages/qIJRAE59MAIlG03FyJC7" %}
[Payment for private channel subscription](/for-subscribers/how-to-pay-for-a-subscription/payment-for-private-channel-subscription)
{% endcontent-ref %}
{% content-ref url="/pages/nAoDenSYZ6RWnv9XVWEn" %}
[Payment for public channel subscription](/for-subscribers/how-to-pay-for-a-subscription/payment-for-public-channel-subscription)
{% endcontent-ref %}
# Payment for private channel subscription
1. Follow the link that the channel creator generated to subscribe to the private channel.
2. Click «Request to Join Channel».
3. The **@Tribute** bot will send you a message with a subscription, click the button below that message.
4. Next, the subscription details will be displayed, click «Continue».
5. Select «Payment Method» (if a card has already been added, skip to step #7).
6. Enter the card details and click «Done».
7. Click «Pay».
8. Done, your subscription is purchased. Click «Open Channel» to go to the channel.
# Payment for public channel subscription
1. Click on the button below the subscription message (the button may have different names).
2. A confirmation window for launching the **@Tribute** bot will open, click «Launch» (if you are opening the bot for the first time).
3. Next, the subscription details will be displayed, click «Continue».
4. Select «Payment Method» (if a card has already been added, skip to step #6).
5. Specify the card details and click «Done».
6. Click «Pay».
7. Done, the subscription is purchased.
# Tribute Energy
We have launched the Tribute Energy bonus system. Now, with each purchase, both subscribers and authors will earn energy. The higher the purchase amount, the greater the chance to earn the maximum energy.
#### **How is energy earned?**
\
Authors with the highest performance will appear in a special ranking – the leaderboard. Check out the leaders, and support your favorite authors to help them stay on top!
Very soon, energy will be exchangeable for bonuses — for both authors and subscribers.
# How to pay for a digital product with a card
We have added an alternative payment method via links in the browser. Now you can pay for digital goods not only with “Stars”, but also with a bank card via a web link — in rubles or euros.
## **How to pay for a digital product via the link**:
1. Follow the web link.
2. Log in via Telegram or email (if you chose the second option, don’t forget to check the “Spam” folder).
3. Enter your bank card details (payment is possible in rubles and euros).
4. All set! After payment, you will receive the digital product in the @tribute Telegram bot.
# How to send a donation
1. Click on the button below the donation message (the button may have different names).
2. A confirmation window for launching the **@Tribute** bot will open, click «Launch» (if you are opening the bot for the first time).
3. Specify the amount of donation (you can enter your own amount) and click «Continue».
4. Select «Payment method» (if the card has already been added, go to step #6).
5. Specify card details and click «Done».
6. Click «Pay».
7. Done, the donation has been sent.
# Subscription management
1. Open «Menu» in the **Tribute** bot.
2. The main screen will display all your subscriptions.
3. Select a subscription if you want to see its details or cancel the subscription.
4. If you want to go to the subscription channel, click on the channel name.
5. Below is information about the subscription, renewal period and payment.
6. Tap «Cancel Subscription» to cancel your subscription.
# Payment methods
#### How to add a new card
1. Open the “Payment methods” section in the subscriber’s profile
2. Click “Add payment method.”
3. Enter the card-issuing country.
4. Enter your payment details.
5. Save the changes and select the card as your primary one.
**What happens next**
* The new card will be saved to your profile.
* Adding a card does not require making a transaction.
* If you want to pay using the added card, click “Set as primary payment method.”
# Payment history
If you want to see your entire transaction history, then:
1. Open «Menu» in the **Tribute** bot.
2. Scroll down the screen to the beginning of the transaction section.
3. Clicking on any of them will open detailed information about the transaction.
# Cashback
Tribute users can earn cashback on donations and digital product purchases via [@wallet](https://t.me/wallet).
#### How to earn cashback
1. Pay for a digital product or make a donation through [@wallet](https://t.me/wallet); it doesn't matter what currency you use to make the payment.
2. Tribute will credit 3% of that amount, convert it to TON, and send it to your @wallet. The conversion rate is calculated at the time of the transaction.
3. You will receive the cashback in TON two weeks after the purchase. Cashback transactions will be displayed in the Tribute bot.
4. The minimum payout amount is 0.000001 TON. If the cashback does not reach the minimum amount, it will accumulate.
# Shop API
### Authorization
To access the Tribute API, you need to obtain an API key through the settings.
#### How to get an API key
1. Open the Tribute web application in Telegram
2. Click on the three dots **(⋯)** in the upper right corner and select "**Settings**" from the context menu
3. Go to the "**API Keys**" section
4. Click the "**Generate API Key**" button and copy it to a safe place
#### Using the API key
The key is passed in the `Api-Key` header in every HTTPS request to the API.
**Example using curl:**
```bash
curl -X GET \
'https://tribute.tg/api/v1/shops' \
-H 'Api-Key: your_api_key_here'
```
# 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.
## List Shops
> Returns the authenticated user's active shops, ordered by creation (oldest first). Inactive shops are never listed. Single-shop owners always see one element; multi-shop owners use this endpoint to discover shop IDs to pass to the other shop endpoints via \`?shopId=\`.
```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":{"Shop":{"type":"object","required":["id","userId","name","link","callbackUrl","recurrent","onlyStars","tokenCharging","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]}}},"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":{"/shops":{"get":{"summary":"List Shops","description":"Returns the authenticated user's active shops, ordered by creation (oldest first). Inactive shops are never listed. Single-shop owners always see one element; multi-shop owners use this endpoint to discover shop IDs to pass to the other shop endpoints via `?shopId=`.","tags":["Methods"],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Shop"}}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Shop
> Returns shop information for the authenticated user. Only active shops are returned. Pass \`?shopId=\` to target a specific shop; omitting it returns the user's oldest active shop. An explicit \`shopId\` for an inactive (but owned) shop returns \`error\_shop\_inactive\`.
```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. Only active shops are returned. Pass `?shopId=` to target a specific shop; omitting it returns the user's oldest active shop. An explicit `shopId` for an inactive (but owned) shop returns `error_shop_inactive`.","tags":["Methods"],"parameters":[{"name":"shopId","in":"query","required":false,"schema":{"type":"integer","format":"uint64"},"description":"ID of the active shop to return. Defaults to the oldest active shop owned by the authenticated user."}],"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. Pass \`?shopId=\` to target a specific shop; omitting it returns orders for the oldest shop.
```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. `prepaid` is opt-in (per-seller rollout): card-to-Stars orders where stars have been credited to the buyer but the buyer has not yet confirmed the Telegram Stars charge. Sellers not opted in see `pending` instead.\n\nA card decline does not change the status — the order stays `pending` and payable.\n","enum":["pending","prepaid","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`null` for orders created through a payment link — such orders are paid only via the link's checkout (see `paymentLinkUuid`).\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment. Empty for orders created through a payment link — they are paid only via the link's `webappPaymentUrl`."},"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)"},"memberInTrial":{"type":"boolean","description":"True while an active member is still inside the free trial window (subscribed, not yet charged). Present whenever a member exists — `false` for non-trial members and after the trial converts or the member is cancelled. Omitted only when there is no member."},"memberTrialStartedAt":{"type":"string","format":"date-time","description":"Trial start (subscription time), in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"memberTrialEndsAt":{"type":"string","format":"date-time","description":"Trial end / first-charge date, in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. If set, the initial charge used this amount; subsequent charges use `amount`. Absent for orders without a first-period override.\n"},"sendEmail":{"type":"boolean","description":"Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)"},"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"]}}},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link this order was created through. Absent for ordinary orders."}}},"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. Pass `?shopId=` to target a specific shop; omitting it returns orders for the oldest shop.","tags":["Methods"],"parameters":[{"name":"shopId","in":"query","required":false,"schema":{"type":"integer","format":"uint64"},"description":"ID of the shop to read orders from. Defaults to the oldest shop owned by the authenticated user."},{"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"},{"name":"paymentLinkUuid","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only orders created through this payment link (see Payment Links). The link must belong to the shop, otherwise 404."}],"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":{"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. `prepaid` is opt-in (per-seller rollout): card-to-Stars orders where stars have been credited to the buyer but the buyer has not yet confirmed the Telegram Stars charge. Sellers not opted in see `pending` instead.\n\nA card decline does not change the status — the order stays `pending` and payable.\n","enum":["pending","prepaid","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`null` for orders created through a payment link — such orders are paid only via the link's checkout (see `paymentLinkUuid`).\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment. Empty for orders created through a payment link — they are paid only via the link's `webappPaymentUrl`."},"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)"},"memberInTrial":{"type":"boolean","description":"True while an active member is still inside the free trial window (subscribed, not yet charged). Present whenever a member exists — `false` for non-trial members and after the trial converts or the member is cancelled. Omitted only when there is no member."},"memberTrialStartedAt":{"type":"string","format":"date-time","description":"Trial start (subscription time), in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"memberTrialEndsAt":{"type":"string","format":"date-time","description":"Trial end / first-charge date, in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. If set, the initial charge used this amount; subsequent charges use `amount`. Absent for orders without a first-period override.\n"},"sendEmail":{"type":"boolean","description":"Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)"},"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"]}}},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link this order was created through. Absent for ordinary orders."}}},"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":["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).\nRequired for regular shops. Ignored for OnlyStars shops — the order is stored with `amount=0` and the charge is settled in Telegram Stars (via `starsAmount`). `currency` is required either way.\n"},"currency":{"type":"string","description":"Currency code (lowercase). Required for every order, including OnlyStars shops — it determines the fiat price shown on the invoice (derived from `starsAmount` for OnlyStars orders).\n","enum":["eur","rub","usd"]},"title":{"type":"string","description":"Order title (required, max 100 UTF-16 characters). Leading/trailing whitespace is trimmed; a whitespace-only value is rejected."},"description":{"type":"string","description":"Order description (required, max 300 UTF-16 characters). Leading/trailing whitespace is trimmed; a whitespace-only value is rejected."},"successUrl":{"type":"string","format":"uri","description":"Redirect URL on successful payment (optional, must be a valid https:// URL)"},"failUrl":{"type":"string","format":"uri","description":"Redirect URL on failed payment (optional, must be a valid https:// URL)"},"email":{"type":"string","format":"email","description":"Customer email (optional, validated if provided). When set, the buyer isn't asked to enter an email at checkout (the address itself stays server-side). A receipt is only sent when the shop has `sendEmail=true`.\n"},"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."},"firstPeriodAmount":{"type":"integer","format":"int64","description":"Price of the first recurring period in smallest currency units (cents/kopecks). When set, the initial charge uses this amount; every subsequent charge uses `amount`. May be lower (promo) or higher than `amount`. Same currency-range limits apply as for `amount`. Must differ from `amount`.\n\nRequires `period != onetime`. Not allowed for OnlyStars shops. Mutually exclusive with `starsAmount`: an order may offer a first-period fiat override **or** a fixed Stars price, not both. The platform applies the value as supplied and does not deduplicate per buyer.\n"},"trialPeriod":{"type":"string","enum":["one_hour","twelve_hours","twenty_four_hours","three_days","seven_days"],"description":"Grants a **free trial** window to buyers who pay by card. During the trial the buyer is not charged; at trial end the first paid charge is `firstPeriodAmount` (if set) otherwise `amount`, and every subsequent period is `amount`.\n\nCard-only: SBP, Wallet and Telegram Stars ignore the trial and charge as usual. Requires `period != onetime`. Not allowed for OnlyStars shops. Combinable with `firstPeriodAmount`. A repeat trial on the same order is not granted.\n"}}}}}},"responses":{"200":{"description":"Order created successfully. Returns the full order object — the same\nshape as `GET /shop/orders/{orderUuid}`. `paymentUrl` is `null` for\nOnlyStars orders.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopOrder"}}}},"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. `prepaid` is opt-in (per-seller rollout): card-to-Stars orders where stars have been credited to the buyer but the buyer has not yet confirmed the Telegram Stars charge. Sellers not opted in see `pending` instead.\n\nA card decline does not change the status — the order stays `pending` and payable.\n","enum":["pending","prepaid","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`null` for orders created through a payment link — such orders are paid only via the link's checkout (see `paymentLinkUuid`).\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment. Empty for orders created through a payment link — they are paid only via the link's `webappPaymentUrl`."},"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)"},"memberInTrial":{"type":"boolean","description":"True while an active member is still inside the free trial window (subscribed, not yet charged). Present whenever a member exists — `false` for non-trial members and after the trial converts or the member is cancelled. Omitted only when there is no member."},"memberTrialStartedAt":{"type":"string","format":"date-time","description":"Trial start (subscription time), in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"memberTrialEndsAt":{"type":"string","format":"date-time","description":"Trial end / first-charge date, in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. If set, the initial charge used this amount; subsequent charges use `amount`. Absent for orders without a first-period override.\n"},"sendEmail":{"type":"boolean","description":"Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)"},"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"]}}},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link this order was created through. Absent for ordinary orders."}}},"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":"shopId","in":"query","required":false,"schema":{"type":"integer","format":"uint64"},"description":"ID of the shop to read orders from. Defaults to the oldest shop owned by the authenticated user."},{"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\n`prepaid` is opt-in (per-seller rollout) and returns shop orders in the card-to-Stars flow where stars have been credited but the buyer has not yet confirmed the Telegram Stars charge. Requesting `prepaid` without opt-in returns HTTP 400.\n","required":false,"schema":{"type":"string","enum":["all","pending","prepaid","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"},{"name":"paymentLinkUuid","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Only orders created through this payment link (see Payment Links). The link must belong to the shop, otherwise 404."}],"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. `prepaid` is opt-in (per-seller rollout): card-to-Stars orders where stars have been credited to the buyer but the buyer has not yet confirmed the Telegram Stars charge. Sellers not opted in see `pending` instead.\n\nA card decline does not change the status — the order stays `pending` and payable.\n","enum":["pending","prepaid","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`null` for orders created through a payment link — such orders are paid only via the link's checkout (see `paymentLinkUuid`).\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment. Empty for orders created through a payment link — they are paid only via the link's `webappPaymentUrl`."},"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)"},"memberInTrial":{"type":"boolean","description":"True while an active member is still inside the free trial window (subscribed, not yet charged). Present whenever a member exists — `false` for non-trial members and after the trial converts or the member is cancelled. Omitted only when there is no member."},"memberTrialStartedAt":{"type":"string","format":"date-time","description":"Trial start (subscription time), in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"memberTrialEndsAt":{"type":"string","format":"date-time","description":"Trial end / first-charge date, in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. If set, the initial charge used this amount; subsequent charges use `amount`. Absent for orders without a first-period override.\n"},"sendEmail":{"type":"boolean","description":"Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)"},"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"]}}},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link this order was created through. Absent for ordinary orders."}}},"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. `prepaid` (card-to-Stars: stars credited to buyer, awaiting charge confirmation) is returned only for sellers opted in to the prepaid rollout — others see `pending` until the buyer finalizes the charge.\n","enum":["pending","prepaid","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"}}}}}}}}}
```
## Resend Shop Order Webhook
> Re-delivers the latest already-attempted webhook of the given event type for a shop order, by cloning it into a new delivery attempt. Only accessible by the shop owner or authorized managers. Events still queued or in flight cannot be resent. Idempotent while a re-delivery is queued (returns 200 without scheduling another one); at most one resend per event type per order per minute.
```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}/webhooks/resend":{"post":{"summary":"Resend Shop Order Webhook","description":"Re-delivers the latest already-attempted webhook of the given event type for a shop order, by cloning it into a new delivery attempt. Only accessible by the shop owner or authorized managers. Events still queued or in flight cannot be resent. Idempotent while a re-delivery is queued (returns 200 without scheduling another one); at most one resend per event type per order per minute.","tags":["Methods"],"parameters":[{"name":"orderUuid","in":"path","description":"Order UUID","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["event"],"properties":{"event":{"type":"string","description":"Webhook event type to resend","enum":["shop_order","shop_order_charge_success","shop_order_charge_failed","shop_order_cancelled","shop_order_refunded","shop_order_payment_received","shop_order_payment_failed","shop_order_prepaid","shop_token_charge_success","shop_token_charge_failed"]}}}}}},"responses":{"200":{"description":"Resend scheduled successfully","content":{"application/json":{"schema":{"type":"object","required":["success"],"properties":{"success":{"type":"boolean","description":"Whether the resend was scheduled"}}}}}},"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 a webhook of this event type not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded - one resend per event type per order per minute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Payment Links
Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.
Not to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.
| Method | Availability on a payment link |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |
| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |
OnlyStars shops cannot create payment links. Recurring payments are not supported.
## Get Payment Links
> Returns the shop's payment links sorted by ID descending (newest first), paginated (up to 100 per page). Optionally filter by customer, status and creation date range. Pass \`?shopId=\` to target a specific shop; omitting it returns links for the oldest shop.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Payment Links","description":"Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.\n\nNot to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.\n\n| Method | Availability on a payment link |\n|--------|-------------|\n| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |\n| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |\n\nOnlyStars shops cannot create payment links. Recurring payments are not supported.\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":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}},"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/payment_links":{"get":{"summary":"Get Payment Links","description":"Returns the shop's payment links sorted by ID descending (newest first), paginated (up to 100 per page). Optionally filter by customer, status and creation date range. Pass `?shopId=` to target a specific shop; omitting it returns links for the oldest shop.","tags":["Payment Links"],"parameters":[{"name":"size","in":"query","required":false,"schema":{"type":"integer","default":100,"maximum":100},"description":"Links per page (1–100)."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page number, 1-based."},{"name":"shopId","in":"query","required":false,"schema":{"type":"integer","format":"uint64"},"description":"ID of the shop to read links from. Defaults to the oldest shop owned by the authenticated user."},{"name":"customerId","in":"query","required":false,"schema":{"type":"string"},"description":"Only links created for this customer (exact match)."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["active","deactivated"]},"description":"Only links with this status."},{"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/ShopPaymentLink"}}}}},"400":{"description":"Invalid status or date range","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"}}}}}}}}}
```
## Create Payment Link
> Creates a \*\*reusable payment link\*\* for a customer. Send it to the customer once — it can be paid any number of times.\
> \
> Opening the link in Telegram (\`webappPaymentUrl\`) shows a checkout where the customer chooses the amount (the link's \`defaultAmount\` is preselected; amount presets are generated by the app) and a payment method. \*\*Every payment creates an ordinary one-time shop order\*\* for the chosen amount, so it flows through the usual \`shop\_order\` webhook, refunds, receipts and token charging. Orders born from a link carry \`paymentLinkUuid\`, and the \`shop\_order\` / \`shop\_order\_payment\_failed\` / \`shop\_order\_refunded\` webhooks carry \`paymentLinkUuid\`, \`customerId\` and the link's \`payload\`.\
> \
> \*\*Naming:\*\* a \*payment link\* is this reusable entity. \`paymentUrl\` / \`webappPaymentUrl\` on an order are that order's one-time checkout links.\
> \
> \*\*Payment methods:\*\* every method available to the shop's one-time orders. Native Telegram Stars is offered as well: the chosen amount is converted to Stars at the current rate when the order is created; if the result falls outside the Stars limits (1–5000), Stars is not offered for that amount. Token-charging shops accept Stars on link orders too — a Stars payment simply vaults no card token.\
> \
> \*\*Limits:\*\* one-time payments only (no recurring). Not available for OnlyStars shops. Amount limits are the platform currency limits (EUR/USD 1–3000, RUB 100–300 000). Shop settings (fee, receipts, …) are applied to each new order at payment time. An order created from a link stays payable for 24 hours — its Stars price is fixed at creation — after that the customer opens the link again and gets a fresh order at the current rate. Telegram Mini App only — there is no web checkout page for links.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Payment Links","description":"Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.\n\nNot to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.\n\n| Method | Availability on a payment link |\n|--------|-------------|\n| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |\n| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |\n\nOnlyStars shops cannot create payment links. Recurring payments are not supported.\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":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}},"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/payment_links":{"post":{"summary":"Create Payment Link","description":"Creates a **reusable payment link** for a customer. Send it to the customer once — it can be paid any number of times.\n\nOpening the link in Telegram (`webappPaymentUrl`) shows a checkout where the customer chooses the amount (the link's `defaultAmount` is preselected; amount presets are generated by the app) and a payment method. **Every payment creates an ordinary one-time shop order** for the chosen amount, so it flows through the usual `shop_order` webhook, refunds, receipts and token charging. Orders born from a link carry `paymentLinkUuid`, and the `shop_order` / `shop_order_payment_failed` / `shop_order_refunded` webhooks carry `paymentLinkUuid`, `customerId` and the link's `payload`.\n\n**Naming:** a *payment link* is this reusable entity. `paymentUrl` / `webappPaymentUrl` on an order are that order's one-time checkout links.\n\n**Payment methods:** every method available to the shop's one-time orders. Native Telegram Stars is offered as well: the chosen amount is converted to Stars at the current rate when the order is created; if the result falls outside the Stars limits (1–5000), Stars is not offered for that amount. Token-charging shops accept Stars on link orders too — a Stars payment simply vaults no card token.\n\n**Limits:** one-time payments only (no recurring). Not available for OnlyStars shops. Amount limits are the platform currency limits (EUR/USD 1–3000, RUB 100–300 000). Shop settings (fee, receipts, …) are applied to each new order at payment time. An order created from a link stays payable for 24 hours — its Stars price is fixed at creation — after that the customer opens the link again and gets a fresh order at the current rate. Telegram Mini App only — there is no web checkout page for links.\n","tags":["Payment Links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["currency","defaultAmount","title","description","customerId"],"properties":{"shopId":{"type":"integer","format":"uint64","description":"ID of the shop to create the link in. Defaults to the oldest shop owned by the authenticated user."},"currency":{"type":"string","enum":["eur","rub","usd"],"description":"Currency of the amounts the customer can choose."},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units (cents/kopecks). Must be within the platform limits for the currency."},"title":{"type":"string","maxLength":100,"description":"Shown on the checkout and copied to every order."},"description":{"type":"string","maxLength":300,"description":"Shown on the checkout and copied to every order."},"customerId":{"type":"string","maxLength":256,"description":"Your identifier of the customer this link is for. Copied to every order and returned in webhooks."},"email":{"type":"string","format":"email","description":"Customer email (optional, validated if provided). Copied to every order created through the link, so the buyer isn't asked to enter an email at checkout (the address itself stays server-side). A receipt is only sent when the shop has `sendEmail=true`.\n"},"payload":{"description":"Any JSON value (object, array, string, …) up to 4 KB, e.g. the identifier of the creator on your side. Returned as-is in the webhooks of every order created through the link."}}}}}},"responses":{"200":{"description":"Payment link created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopPaymentLink"}}}},"400":{"description":"Validation error","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 Payment Link
> Returns a payment link by UUID. The link must belong to the authenticated user.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Payment Links","description":"Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.\n\nNot to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.\n\n| Method | Availability on a payment link |\n|--------|-------------|\n| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |\n| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |\n\nOnlyStars shops cannot create payment links. Recurring payments are not supported.\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":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}},"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/payment_links/{linkUuid}":{"get":{"summary":"Get Payment Link","description":"Returns a payment link by UUID. The link must belong to the authenticated user.","tags":["Payment Links"],"parameters":[{"name":"linkUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Payment link UUID"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopPaymentLink"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The link belongs to another user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Payment link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Deactivate Payment Link
> Deactivates a payment link (shortcut for \`PATCH\` with \`status: deactivated\`). It stops accepting payments immediately — the checkout no longer opens, and orders already created through the link can no longer be paid. Already paid orders are unaffected. Idempotent; reactivate with \`PATCH\`.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Payment Links","description":"Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.\n\nNot to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.\n\n| Method | Availability on a payment link |\n|--------|-------------|\n| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |\n| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |\n\nOnlyStars shops cannot create payment links. Recurring payments are not supported.\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":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}},"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/payment_links/{linkUuid}":{"delete":{"summary":"Deactivate Payment Link","description":"Deactivates a payment link (shortcut for `PATCH` with `status: deactivated`). It stops accepting payments immediately — the checkout no longer opens, and orders already created through the link can no longer be paid. Already paid orders are unaffected. Idempotent; reactivate with `PATCH`.","tags":["Payment Links"],"parameters":[{"name":"linkUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Payment link UUID"}],"responses":{"200":{"description":"Payment link deactivated (returns the link with `status: deactivated`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopPaymentLink"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The link belongs to another user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Payment link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Update Payment Link Status
> Switches a payment link between \`active\` and \`deactivated\`. Deactivation takes effect immediately (the checkout no longer opens, unpaid orders created through the link can no longer be paid); reactivation makes the same link — and those unpaid orders — payable again. Idempotent in both directions.
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"tags":[{"name":"Payment Links","description":"Reusable payment links: create one per customer, send it once, get paid any number of times. The customer chooses the amount on a Telegram Mini App checkout; **every payment creates an ordinary one-time shop order**, so orders, webhooks, refunds and receipts work exactly as for orders you create yourself.\n\nNot to be confused with `paymentUrl` / `webappPaymentUrl` on an order — those are one-time checkout links of a specific order.\n\n| Method | Availability on a payment link |\n|--------|-------------|\n| Bank cards, SBP, Wallet Pay | As for the shop's one-time orders |\n| Telegram Stars | Offered when the chosen amount converts to 1–5000 Stars at the current rate (token-charging shops included; no card token is vaulted for a Stars payment) |\n\nOnlyStars shops cannot create payment links. Recurring payments are not supported.\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":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}},"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/payment_links/{linkUuid}":{"patch":{"summary":"Update Payment Link Status","description":"Switches a payment link between `active` and `deactivated`. Deactivation takes effect immediately (the checkout no longer opens, unpaid orders created through the link can no longer be paid); reactivation makes the same link — and those unpaid orders — payable again. Idempotent in both directions.","tags":["Payment Links"],"parameters":[{"name":"linkUuid","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Payment link UUID"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["active","deactivated"]}}}}}},"responses":{"200":{"description":"Updated payment link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ShopPaymentLink"}}}},"400":{"description":"Unknown status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"The link belongs to another user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Payment link not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
# Webhooks
Webhook notifications for shop events.
**Setup:**
1. Go to Creator Dashboard → Settings (three-dot menu) → API Keys section
2. Generate API key if you haven't already
3. Specify your webhook URL in the webhook settings
**Signature verification:** Each request contains `trbt-signature` header with HMAC-SHA256 signature of request body signed with your API key.
**Retry attempts:** On delivery failure, system retries with exponential backoff over \~24 hours: 5min, 15min, 30min, 1h, 2h, 4h, 8h, 8h.
{% openapi-webhook spec="shop-en" name="shopOrder" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderChargeFailed" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderChargeSuccess" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderCancelled" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderRefunded" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderPaymentFailed" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="shop-en" name="shopOrderPaymentReceived" method="post" %}
[shop-en](https://tribute.tg/api/v1/openapi/shop/en)
{% endopenapi-webhook %}
# Models
## The Error object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"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"}}}}}}
```
## The Shop object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"Shop":{"type":"object","required":["id","userId","name","link","callbackUrl","recurrent","onlyStars","tokenCharging","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]}}}}}}
```
## The ShopOrder object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"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. `prepaid` is opt-in (per-seller rollout): card-to-Stars orders where stars have been credited to the buyer but the buyer has not yet confirmed the Telegram Stars charge. Sellers not opted in see `pending` instead.\n\nA card decline does not change the status — the order stays `pending` and payable.\n","enum":["pending","prepaid","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`null` for orders created through a payment link — such orders are paid only via the link's checkout (see `paymentLinkUuid`).\n"},"webappPaymentUrl":{"type":"string","format":"uri","description":"Telegram WebApp payment URL for in-app payment. Empty for orders created through a payment link — they are paid only via the link's `webappPaymentUrl`."},"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)"},"memberInTrial":{"type":"boolean","description":"True while an active member is still inside the free trial window (subscribed, not yet charged). Present whenever a member exists — `false` for non-trial members and after the trial converts or the member is cancelled. Omitted only when there is no member."},"memberTrialStartedAt":{"type":"string","format":"date-time","description":"Trial start (subscription time), in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"memberTrialEndsAt":{"type":"string","format":"date-time","description":"Trial end / first-charge date, in ISO 8601 format. Present for an active trial member — both while in trial and after it converts (then historical). Omitted for non-trial and cancelled members."},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. If set, the initial charge used this amount; subsequent charges use `amount`. Absent for orders without a first-period override.\n"},"sendEmail":{"type":"boolean","description":"Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)"},"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"]}}},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link this order was created through. Absent for ordinary orders."}}}}}}
```
## The ShopPaymentLink object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopPaymentLink":{"type":"object","description":"A reusable payment link. Each payment through it creates a one-time shop order for the amount the customer chose.","required":["uuid","shopId","title","description","currency","defaultAmount","customerId","status","webappPaymentUrl","createdAt"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Public identifier of the link"},"shopId":{"type":"integer","format":"uint64"},"title":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","enum":["eur","rub","usd"]},"defaultAmount":{"type":"integer","format":"int64","description":"Amount preselected on the checkout, in smallest currency units"},"email":{"type":"string","format":"email","description":"Customer email copied to every order created through the link; omitted when not set"},"customerId":{"type":"string"},"payload":{"nullable":true,"description":"The JSON value supplied at creation, returned as-is in webhooks"},"status":{"type":"string","enum":["active","deactivated"]},"webappPaymentUrl":{"type":"string","description":"Telegram Mini App checkout link to send to the customer (reusable)"},"createdAt":{"type":"string","format":"date-time"},"deactivatedAt":{"type":"string","format":"date-time","description":"Present once the link is deactivated"}}}}}}
```
## The ShopOrderPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderPayload":{"type":"object","required":["uuid","shopId","amount","currency","fee","status","isRecurrent"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"amount":{"type":"integer","format":"int64","description":"The order's regular recurring price — what the 2nd and subsequent\ncharges cost — in smallest currency units (cents/kopecks). For\nrecurring orders with a first-period override, the amount actually\ncharged on this initial CIT is carried by `firstPeriodAmount`.\n"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"fee":{"type":"integer","format":"int64","description":"Platform fee in smallest currency units"},"status":{"type":"string","description":"Order status (webhook is sent only when status = 'paid')","enum":["paid"]},"email":{"type":"string","format":"email","description":"Customer email (optional, may be empty)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"isRecurrent":{"type":"boolean","description":"Whether this is a recurring order"},"period":{"type":"string","description":"Billing period (only for recurring orders)","enum":["weekly","monthly","quarterly","halfyearly","yearly"]},"paymentToken":{"type":"string","format":"uuid","description":"Payment token UUID for merchant-initiated charges (only when tokenCharging is enabled and token was created)"},"cardLast4":{"type":"string","description":"Last 4 digits of the card used for payment (only when tokenCharging is enabled)"},"cardBrand":{"type":"string","description":"Card brand (only when tokenCharging is enabled)"},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units — for this initial paid event, the amount actually charged. Present when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"memberStatus":{"type":"string","description":"Recurring subscription member 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)"},"isTrial":{"type":"boolean","description":"True when this paid event is a free-trial activation — no money was charged yet; the member is active until `trialEndsAt` and the first paid charge (`firstPeriodAmount` when set, otherwise `amount`) fires at trial end."},"trialPeriod":{"type":"string","description":"Configured trial duration (present only for a trial activation).","enum":["one_hour","twelve_hours","twenty_four_hours","three_days","seven_days"]},"trialEndsAt":{"type":"string","format":"date-time","description":"When the free trial ends and the first paid charge is attempted (only for a trial activation)."},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link the order was created through (only for orders born from a payment link)."},"payload":{"description":"The payment link's `payload`, as supplied at link creation (only for orders born from a payment link)."}}}}}}
```
## The ShopOrderChargeFailedPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderChargeFailedPayload":{"type":"object","required":["uuid","shopId","amount","currency","period","chargeRetries"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"amount":{"type":"integer","format":"int64","description":"Amount attempted for the failed recurring period, in smallest\ncurrency units (cents/kopecks). Equals the order's recurring `amount`;\nthe first-period override (`firstPeriodAmount`) only affects the\ninitial CIT, not subsequent recurring charges.\n"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"period":{"type":"string","description":"Billing period","enum":["weekly","monthly","quarterly","halfyearly","yearly"]},"chargeRetries":{"type":"integer","description":"Number of failed charge attempts (1-3). Retry schedule: 2nd attempt ~2h after the first failed attempt, 3rd attempt ~8h after the first failed attempt. After 3 failures, the subscription is cancelled.","minimum":1,"maximum":3},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"isRecurrent":{"type":"boolean","description":"Whether this is a recurring order"},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. Set when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"memberStatus":{"type":"string","description":"Recurring subscription member status","enum":["active","cancelled"]},"memberExpiresAt":{"type":"string","format":"date-time","description":"Recurring subscription expiration date in ISO 8601 format"}}}}}}
```
## The ShopOrderChargeSuccessPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderChargeSuccessPayload":{"type":"object","required":["uuid","shopId","amount","currency","period"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"amount":{"type":"integer","format":"int64","description":"Amount charged for the current recurring period, in smallest currency\nunits (cents/kopecks). Equals the order's recurring `amount`; the\nfirst-period override (`firstPeriodAmount`) only affects the initial CIT,\nnot subsequent recurring charges.\n"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"period":{"type":"string","description":"Billing period","enum":["weekly","monthly","quarterly","halfyearly","yearly"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"isRecurrent":{"type":"boolean","description":"Whether this is a recurring order"},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. Set when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"memberStatus":{"type":"string","description":"Recurring subscription member status","enum":["active","cancelled"]},"memberExpiresAt":{"type":"string","format":"date-time","description":"Recurring subscription expiration date in ISO 8601 format"}}}}}}
```
## The ShopOrderCancelledPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderCancelledPayload":{"type":"object","required":["uuid","shopId","amount","currency","period","cancelReason"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"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"]},"period":{"type":"string","description":"Billing period","enum":["weekly","monthly","quarterly","halfyearly","yearly"]},"cancelReason":{"type":"string","description":"Reason for cancellation.\n- `cancelled_by_seller` — cancelled by the shop owner.\n- `charge_failed` — recurring card charge could not be completed (e.g. all retry attempts exhausted, stale pending invoice, internal processing failure).\n- `payment_method_expired` — saved payment method (card) is no longer usable.\n- `stars_subscription_expired` — Telegram Stars subscription stopped renewing on Telegram's side. Covers both pure-Stars subscriptions (no fiat card on file; renewal is handled by Telegram) and OnlyStars card-to-Stars subscriptions whose buyer cancelled on Telegram's side (the card pre-charge is then stopped).\n- `seller_unavailable` — seller can no longer accept payments (account banned/deleted, payments disabled, or verification requirements not met).\n- `last_charge_refunded` — the buyer's most recently created shop-order buyer transaction was refunded. Refunding an older charge while a newer one still exists does NOT cancel the subscription.\n","enum":["cancelled_by_seller","charge_failed","payment_method_expired","stars_subscription_expired","seller_unavailable","last_charge_refunded"]},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"isRecurrent":{"type":"boolean","description":"Whether this is a recurring order"},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. Set when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"memberStatus":{"type":"string","description":"Recurring subscription member 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)"}}}}}}
```
## The ShopToken object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopToken":{"type":"object","required":["shopId","token","cardLast4","cardBrand","amount","currency","active","createdAt"],"properties":{"shopId":{"type":"integer","format":"uint64","description":"Shop ID this token belongs to"},"token":{"type":"string","format":"uuid","description":"Payment token UUID"},"cardLast4":{"type":"string","description":"Last 4 digits of the card number"},"cardBrand":{"type":"string","description":"Card brand (VISA, MASTERCARD, etc.)"},"customerId":{"type":"string","description":"Merchant's customer reference (optional)"},"amount":{"type":"integer","format":"int64","description":"Fixed charge amount in smallest currency units"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"active":{"type":"boolean","description":"Whether the token is active and can be charged"},"createdAt":{"type":"string","format":"date-time","description":"Token creation timestamp in ISO 8601 format"},"lastUsedAt":{"type":"string","format":"date-time","description":"Last time the token was charged (optional)"}}}}}}
```
## The ShopCharge object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopCharge":{"type":"object","required":["chargeUuid","shopId","status","amount","currency","createdAt"],"properties":{"chargeUuid":{"type":"string","format":"uuid","description":"Charge UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID this charge belongs to"},"status":{"type":"string","description":"Charge status","enum":["pending","processing","success","failed","timeout"]},"reference":{"type":"string","description":"Merchant reference (optional)"},"amount":{"type":"integer","format":"int64","description":"Charge amount in smallest currency units"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"token":{"type":"string","format":"uuid","description":"Payment token UUID"},"errorCode":{"type":"string","description":"Error code if charge failed (optional)"},"errorMessage":{"type":"string","description":"Error message if charge failed (optional)"},"createdAt":{"type":"string","format":"date-time","description":"Charge creation timestamp in ISO 8601 format"},"processedAt":{"type":"string","format":"date-time","description":"Charge processing completion timestamp (optional)"}}}}}}
```
## The ShopTokenChargeSuccessPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopTokenChargeSuccessPayload":{"type":"object","required":["chargeUuid","shopId","token","amount","currency","processedAt"],"properties":{"chargeUuid":{"type":"string","format":"uuid","description":"Charge UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"token":{"type":"string","format":"uuid","description":"Payment token UUID"},"amount":{"type":"integer","format":"int64","description":"Charge amount in smallest currency units"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"reference":{"type":"string","description":"Merchant reference (optional)"},"processedAt":{"type":"string","format":"date-time","description":"Charge completion timestamp in ISO 8601 format"}}}}}}
```
## The ShopTokenChargeFailedPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopTokenChargeFailedPayload":{"type":"object","required":["chargeUuid","shopId","token","amount","currency","errorCode","errorMessage"],"properties":{"chargeUuid":{"type":"string","format":"uuid","description":"Charge UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"token":{"type":"string","format":"uuid","description":"Payment token UUID"},"amount":{"type":"integer","format":"int64","description":"Charge amount in smallest currency units"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"reference":{"type":"string","description":"Merchant reference (optional)"},"errorCode":{"type":"string","description":"Error code"},"errorMessage":{"type":"string","description":"Detailed error message"}}}}}}
```
## The ShopOrderRefundedPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderRefundedPayload":{"type":"object","required":["uuid","shopId","transactionId","amount","currency","status"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"transactionId":{"type":"integer","format":"uint64","description":"ID of the refunded transaction"},"amount":{"type":"integer","format":"int64","description":"Refunded amount in smallest currency units (cents/kopecks)"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"status":{"type":"string","description":"Refund status","enum":["initiated","completed"]},"refundedAt":{"type":"string","format":"date-time","description":"Time when the refund was completed (optional, only present when status is 'completed')"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"isRecurrent":{"type":"boolean","description":"Whether this is a recurring order"},"period":{"type":"string","description":"Billing period","enum":["onetime","weekly","monthly","quarterly","halfyearly","yearly"]},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units. Set when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"memberStatus":{"type":"string","description":"Recurring subscription member 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)"},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link the order was created through (only for orders born from a payment link)."},"payload":{"description":"The payment link's `payload` (only for orders born from a payment link)."}}}}}}
```
## The ShopOrderPaymentFailedPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderPaymentFailedPayload":{"type":"object","required":["uuid","shopId","amount","currency","errorCode","errorMessage"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"amount":{"type":"integer","format":"int64","description":"The order's regular recurring price — what the 2nd and subsequent\ncharges cost — in smallest currency units (cents/kopecks). For\nrecurring orders with a first-period override, the amount that was\nactually attempted on this initial CIT is carried by `firstPeriodAmount`.\n"},"currency":{"type":"string","description":"Currency code (lowercase)","enum":["eur","rub","usd"]},"errorCode":{"type":"string","description":"`payment_declined` — bank decline; `payment_failed` — processing failure after authorization","enum":["payment_declined","payment_failed"]},"errorMessage":{"type":"string","description":"Human-readable error message describing the failure reason"},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"},"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"},"firstPeriodAmount":{"type":"integer","format":"int64","nullable":true,"description":"First-period price in smallest currency units — for this failed initial CIT, the amount that was attempted. Present when the seller supplied `firstPeriodAmount` at order creation; absent otherwise."},"paymentLinkUuid":{"type":"string","format":"uuid","description":"UUID of the payment link the order was created through (only for orders born from a payment link)."},"payload":{"description":"The payment link's `payload` (only for orders born from a payment link)."}}}}}}
```
## The ShopOrderPrepaidPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderPrepaidPayload":{"type":"object","required":["uuid","shopId","amount","currency","starsAmount","onlyStars","starsPurchaseId"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"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"]},"period":{"type":"string","description":"Subscription period (omitted for one-time orders)"},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars credited to the buyer"},"onlyStars":{"type":"boolean","description":"Always true for this event (card-to-Stars flow)"},"starsPurchaseId":{"type":"integer","format":"uint64","description":"Internal identifier for event correlation"},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"}}}}}}
```
## The ShopOrderPaymentReceivedPayload object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"schemas":{"ShopOrderPaymentReceivedPayload":{"type":"object","required":["uuid","shopId","amount","currency","starsAmount","onlyStars","starsPurchaseId"],"properties":{"uuid":{"type":"string","format":"uuid","description":"Order UUID"},"shopId":{"type":"integer","format":"uint64","description":"Shop ID"},"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"]},"period":{"type":"string","description":"Subscription period (omitted for one-time orders)"},"starsAmount":{"type":"integer","format":"int64","description":"Fixed amount in Telegram Stars"},"onlyStars":{"type":"boolean","description":"Whether this order only accepts Telegram Stars payment"},"starsPurchaseId":{"type":"integer","format":"uint64","description":"Internal identifier for event correlation"},"email":{"type":"string","format":"email","description":"Customer email (optional)"},"customerId":{"type":"string","description":"Merchant's customer identifier (optional, included if set when creating the order)"}}}}}}
```
## The Transaction object
```json
{"openapi":"3.1.0","info":{"title":"Tribute Shop API","version":"1.0.0"},"components":{"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"}}}}}}}}
```
# FAQ
What is Tribute?
Tribute is a convenient service for monetizing your Telegram channel. With the [@Tribute](https://telegram.me/tribute) bot, you can set up paid subscriptions and donations on your channel and start earning from your content or services.
Who is Tribute for?
Tribute is for anyone conducting business or creating content on Telegram. Experts can share their knowledge, conduct consultations, or create interest-based communities. Creatives can showcase behind-the-scenes content and discuss their creative process.
What are the main advantages of Tribute?
It's a Telegram-native service, which is convenient for subscribers: no need to divert them to external platforms. In Tribute, payments can be made with cards from any bank and country. Payments are available in rubles and euros, with cryptocurrency payments (USDT, BTC, TON) coming soon. The commission structure is transparent and simple — 10% commision for all transactions.
There's also a convenient creator’s dashboard for managing subscriptions and donations, with detailed statistics coming soon.
How do I start using the service?
1\. Open Telegram on any device
2\. Search for the @Tribute bot and press the “Start” button.
3\. Add the bot as an administrator to your channel. Grant permission to send, edit, delete messages, and add subscribers.
4\. Set up your [subscriptions](https://wiki.tribute.tg/for-content-creators/subscriptions) or [donations](https://wiki.tribute.tg/for-content-creators/donations) as per the instructions.
5\. Fill in your payment details, select your country, and choose a method for receiving payouts.
Why is an ID required for verification?
Creator verification is a standard procedure to create a reliable and secure environment for authors and subscribers.
As our service processes financial transactions, we must adhere to international regulatory standards, including the “Know Your Customer” (KYC) procedure. This measure is necessary to prevent fraud and ensure all transactions through our service are legitimate. All documents are processed confidentially and used solely for identity verification purposes.
Telegram has officially verified the bot, ensuring its safety for addition as a channel administrator.
What is a subscription?
A subscription is regular financial support from subscribers for unique content or the opportunity to interact with you in private channels. Subscriptions can be one-time, weekly, monthly, or yearly. You set the price, but it must be at least €1 or ₽100 and not more than €3000 or ₽300 000.
What is a donation?
A donation is a voluntary contribution and a token of appreciation from subscribers for the content you publish. Subscribers determine the amount, but it must be at least one Euro or 100 Rubles and at most two thousand Euros or 150,000 Rubles.
Can I set up multiple subscriptions?
Yes, you can set up multiple different subscriptions on one channel. This allows your subscribers to choose the option that suits them best.
Can I connect subscriptions and donations to multiple channels?
Yes, you can connect subscriptions and donations to an unlimited number of your channels.
In which currencies can subscriptions be created?
Currently, subscriptions and donations are available in Rubles and Euros.
From which countries is payment available?
Payments can be made from any country, there are no restrictions.
How are payouts processed?
Payouts are received twice a month: on the 25th and 10th of the month or the next working day. The payout schedule is from the 1st to the 15th and from the 16th to the 31st of each month. The minimum amount for payout to a bank card is 100 Euros. The balance is carried over to the next payout date if the minimum threshold is not reached.
What commission does the service charge?
**10%** (from each successful transaction, this includes fees of the service and payment providers).
Are there any limits on the payment amount?
Subscription, donation, goal, custom digital product:
* **€1, $1** or **₽100** is the minimum one-time transaction.
* **€3,000, $3,000** or **₽300,000** is the maximum single transaction.
Digital product:
* **€1, $1** or **₽100** is the minimum one-time transaction.
* **€1,000, $1,000** or **₽100,000** is the maximum single transaction.
What is a creator’s dashboard?
It's a convenient space within the bot under the "creator’s dashboard" tab, where creators can easily manage subscriptions and donations and store all transaction data. Detailed statistics will be available there soon.
How does a subscriber get access to a private channel?
First, the Tribute bot sends an invoice to your subscriber detailing the subscription price, currency, and billing frequency. After payment, the bot confirms the transaction and, if it's a private channel, automatically adds your subscriber to the channel. Both you and your subscriber will receive a notification about this. The bot also reminds subscribers if their subscription is about to expire and offers to renew it. The bot automatically removes subscribers from the channel if their subscription is not renewed.
You also have the option to invite someone via your link without payment. Create an invitation link for an individual user in the "channel management" tab and send it to them.
What if a user paid for a subscription but didn't get access?
This can only happen due to a technical error. We recommend contacting our 24/7 support service — .
What if a subscriber's payment fails?
Please contact our support service — .
How is a subscription renewed?
The bot will remind the user to renew their subscription. If the user links a card, the subscription will be automatically renewed without any reminders.
Does the subscriber receive a notification to renew the subscription?
Yes, if their card is not linked in the bot.
What if the subscriber doesn't have enough funds on their card?
If the payment fails, we will attempt to withdraw funds from another linked card. The subscription will be canceled if only one card is linked or there are no funds on the others.
Can a user cancel their subscription?
Certainly, users have a profile where they can manage, renew, or cancel all their subscriptions.
Can a subscriber get a refund for a subscription?
Subscription refunds are available in the event of a technical error, such as double billing.
You will need to contact our support team at and describe the situation.
Can I give access for free if I want?
Yes, you also have the option to invite someone via your link without payment. For this, create an invitation link for an individual user in the "channel management" tab and send it to them.
Can I use multiple bots for monetization?
We do not recommend using two bots simultaneously, as this can confuse your subscribers and cause technical issues. If you still need to connect multiple bots, we advise consulting with our support service beforehand — .
Are there any content restrictions?
After you add the [@Tribute](https://telegram.me/tribute) bot as an administrator to one or several channels, we will check your channel for compliance with basic requirements. Your content should not contain insults, discredits, calls to violence, or anything else that could harm you or your subscribers. You can read more about the restrictions in our [guide](https://wiki.tribute.tg/for-content-creators/content-restrictions).
.png?alt=media&token=9d5f467d-0155-4488-8377-f13249dd2682)
.jpg?alt=media&token=54aebeee-ba86-4e3c-ae0f-be131dcf7ca1)
.jpg?alt=media&token=758b3276-532f-436a-889e-6769f6e22158)
.jpg?alt=media&token=3c3b6c51-732a-4948-b5da-88e80eaa5958)
.jpg?alt=media&token=262c19d9-5caf-46e4-b139-075b3a5cde2f)
.jpg?alt=media&token=8da14493-3395-44fa-a2b3-dde78c009980)
.jpg?alt=media&token=75bf1839-3ac6-411f-b17b-6523fa246f8e)
.jpg?alt=media&token=ebf1ed6d-81da-4d76-9bf6-173dd885d561)
.jpg?alt=media&token=981b2af1-f8cc-4176-8e41-18c3873212f0)
.jpg?alt=media&token=ee23ad80-80e6-487c-a0e5-86aa1bc4569e)
.jpg?alt=media&token=4fcb3522-d6e3-46c4-a73b-ff60ccad7bae)
.jpg?alt=media&token=bc04c078-76f8-4372-bcca-b274afa8b5c9)
.jpg?alt=media&token=7e066977-9185-4357-abd9-ee930ada7871)
.jpg?alt=media&token=359cea5a-fb99-4207-b3fd-f7b3fc57fe5e)
.jpg?alt=media&token=6d33e534-8e3c-4454-8a9f-f18c2cc5f6ca)
.jpg?alt=media&token=ba44b45e-f8b0-4cbf-942f-0be22a24d0d3)
.jpg?alt=media&token=05fa2b3c-eb51-474c-9fd9-da8ac5c6eeb0)
.png?alt=media&token=5f787c9d-6a00-4a8f-8dad-ea6d5079caa2)
.png?alt=media&token=996ef689-f711-4800-83f1-b3b02072ae71)
.png?alt=media&token=f5ae4070-2074-43a5-82d8-821929372908)
.jpg?alt=media&token=281e22f9-0970-423d-8c7e-88dec478d5e8)
.jpg?alt=media&token=a6d5a70f-0c0e-49c9-a4dd-40598d6fe3a8)
.jpg?alt=media&token=50c44aff-d5a4-4b3e-94b2-f1437454d1fd)
