Ctrlk
Main page
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

get

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=.

Authorizations
Api-KeystringRequired

API key for authentication.

Responses
200

Successful response

application/json
idinteger · uint64Required

Shop ID

Example: 1
userIdintegerRequired

Shop owner user ID

Example: 123
namestringRequired

Shop name

Example: My Shop
linkstringRequired

Shop link/slug

Example: myshop
callbackUrlstring · uriRequired

Webhook callback URL for order notifications

Example: https://example.com/webhook
recurrentbooleanRequired

Whether recurring payments are available

Example: true
onlyStarsbooleanRequired

Whether only Telegram Stars payment is accepted

Example: false
tokenChargingbooleanRequired

Whether merchant-initiated token charging is enabled

Example: false
statusinteger · enumRequired

Shop status (0 = inactive, 1 = active)

Example: 1Possible values:
get/shops
GET /api/v1/shops HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "id": 1,
    "userId": 123,
    "name": "My Shop",
    "link": "myshop",
    "callbackUrl": "https://example.com/webhook",
    "recurrent": true,
    "onlyStars": false,
    "tokenCharging": false,
    "status": 1
  }
]

Get Shop

get

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.

Authorizations
Api-KeystringRequired

API key for authentication.

Query parameters
shopIdinteger · uint64Optional

ID of the active shop to return. Defaults to the oldest active shop owned by the authenticated user.

Example: 1
Responses
200

Successful response

application/json
idinteger · uint64Required

Shop ID

Example: 1
userIdintegerRequired

Shop owner user ID

Example: 123
namestringRequired

Shop name

Example: My Shop
linkstringRequired

Shop link/slug

Example: myshop
callbackUrlstring · uriRequired

Webhook callback URL for order notifications

Example: https://example.com/webhook
recurrentbooleanRequired

Whether recurring payments are available

Example: true
onlyStarsbooleanRequired

Whether only Telegram Stars payment is accepted

Example: false
tokenChargingbooleanOptional

Whether merchant-initiated token charging is enabled

Example: false
statusinteger · enumRequired

Shop status (0 = inactive, 1 = active)

Example: 1Possible values:
get/shop
GET /api/v1/shop HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "id": 1,
  "userId": 123,
  "name": "My Shop",
  "link": "myshop",
  "callbackUrl": "https://example.com/webhook",
  "recurrent": true,
  "onlyStars": false,
  "tokenCharging": false,
  "status": 1
}

Get Shop Orders

get

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.

Authorizations
Api-KeystringRequired

API key for authentication.

Query parameters
shopIdinteger · uint64Optional

ID of the shop to read orders from. Defaults to the oldest shop owned by the authenticated user.

Example: 1
dateFromstring · dateOptional

Start date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-01-01
dateTostring · dateOptional

End date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-12-31
Responses
200

Successful response

application/json
uuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

Shop ID this order belongs to

Example: 1
amountinteger · int64Required

Order amount in smallest currency units (cents/kopecks)

Example: 100000
currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:
titlestringRequired

Order title (max 100 UTF-16 characters)

Example: Product X
descriptionstringRequired

Order description (max 300 UTF-16 characters)

Example: Detailed product description
statusstring · enumRequired

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.

A card decline does not change the status — the order stays pending and payable.

Example: paidPossible values:
emailstring · emailOptional

Customer email (optional)

Example: customer@example.com
successUrlstring · uriRequired

Redirect URL on successful payment

Example: https://shop.com/success
failUrlstring · uriRequired

Redirect URL on failed payment

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Web URL for customer to complete payment in a browser. null for OnlyStars orders — they can only be paid inside Telegram via webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

Telegram WebApp payment URL for in-app payment

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Order creation timestamp in ISO 8601 format

Example: 2025-11-13T15:04:05Z
commentstringOptional

Optional comment for the order

Example: Special request
periodstring · enumRequired

Billing period for recurring orders

Example: onetimePossible values:
memberStatusstring · enumOptional

Recurring subscription status (only for recurring orders)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Recurring subscription expiration date in ISO 8601 format (only for recurring orders)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

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.

Example: true
memberTrialStartedAtstring · date-timeOptional

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.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

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.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Date of the last paid transaction in ISO 8601 format. Null if no transactions exist.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Fixed amount in Telegram Stars (0 if not set)

Example: 0
onlyStarsbooleanOptional

Whether this order only accepts Telegram Stars payment

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

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.

Example: 50000
sendEmailbooleanOptional

Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)

Example: false
get/shop/orders
GET /api/v1/shop/orders HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "title": "Product X",
    "description": "Detailed product description",
    "status": "paid",
    "email": "customer@example.com",
    "successUrl": "https://shop.com/success",
    "failUrl": "https://shop.com/fail",
    "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
    "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
    "createdAt": "2025-11-13T15:04:05Z",
    "comment": "Special request",
    "period": "onetime",
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z",
    "memberInTrial": true,
    "memberTrialStartedAt": "2025-12-13T15:04:05Z",
    "memberTrialEndsAt": "2025-12-20T15:04:05Z",
    "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "sendEmail": false,
    "image": {
      "id": 123,
      "path": "https://cdn.example.com/image.jpg",
      "thumbnail": "text",
      "width": 800,
      "height": 600,
      "fileType": "image"
    }
  }
]

Create Shop Order

post

Creates a new shop order and returns a payment URL for the customer. Supports one-time and recurring payments.

Authorizations
Api-KeystringRequired

API key for authentication.

Body
shopIdinteger · uint64Optional

Shop ID to create the order for. If omitted, the order is created for the first (oldest) shop of the authenticated user.

Example: 1
amountinteger · int64Optional

Order amount in smallest currency units (cents for EUR/USD, kopecks for RUB). Required 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.

Example: 100000
currencystring · enumRequired

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).

Example: rubPossible values:
titlestringRequired

Order title (required, max 100 UTF-16 characters). Leading/trailing whitespace is trimmed; a whitespace-only value is rejected.

Example: Product X
descriptionstringRequired

Order description (required, max 300 UTF-16 characters). Leading/trailing whitespace is trimmed; a whitespace-only value is rejected.

Example: Detailed product description
successUrlstring · uriOptional

Redirect URL on successful payment (optional, must be a valid https:// URL)

Example: https://shop.com/success
failUrlstring · uriOptional

Redirect URL on failed payment (optional, must be a valid https:// URL)

Example: https://shop.com/fail
emailstring · emailOptional

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.

Example: customer@example.com
commentstringOptional

Optional comment for the order

Example: Special request
customerIdstring · max: 256Optional

Unique customer identifier

Example: user_12345
periodstring · enumOptional

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).

Default: onetimeExample: monthlyPossible values:
starsAmountinteger · int64 · min: 1Optional

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.

Example: 50
imageUrlstring · uriOptional

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.

Example: https://example.com/product-image.jpg
firstPeriodAmountinteger · int64Optional

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.

Requires 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.

Example: 50000
trialPeriodstring · enumOptional

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.

Card-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.

Example: seven_daysPossible values:
Responses
200

Order created successfully. Returns the full order object — the same shape as GET /shop/orders/{orderUuid}. paymentUrl is null for OnlyStars orders.

application/json
uuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

Shop ID this order belongs to

Example: 1
amountinteger · int64Required

Order amount in smallest currency units (cents/kopecks)

Example: 100000
currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:
titlestringRequired

Order title (max 100 UTF-16 characters)

Example: Product X
descriptionstringRequired

Order description (max 300 UTF-16 characters)

Example: Detailed product description
statusstring · enumRequired

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.

A card decline does not change the status — the order stays pending and payable.

Example: paidPossible values:
emailstring · emailOptional

Customer email (optional)

Example: customer@example.com
successUrlstring · uriRequired

Redirect URL on successful payment

Example: https://shop.com/success
failUrlstring · uriRequired

Redirect URL on failed payment

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Web URL for customer to complete payment in a browser. null for OnlyStars orders — they can only be paid inside Telegram via webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

Telegram WebApp payment URL for in-app payment

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Order creation timestamp in ISO 8601 format

Example: 2025-11-13T15:04:05Z
commentstringOptional

Optional comment for the order

Example: Special request
periodstring · enumRequired

Billing period for recurring orders

Example: onetimePossible values:
memberStatusstring · enumOptional

Recurring subscription status (only for recurring orders)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Recurring subscription expiration date in ISO 8601 format (only for recurring orders)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

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.

Example: true
memberTrialStartedAtstring · date-timeOptional

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.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

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.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Date of the last paid transaction in ISO 8601 format. Null if no transactions exist.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Fixed amount in Telegram Stars (0 if not set)

Example: 0
onlyStarsbooleanOptional

Whether this order only accepts Telegram Stars payment

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

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.

Example: 50000
sendEmailbooleanOptional

Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)

Example: false
post/shop/orders
POST /api/v1/shop/orders HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 409

{
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Product X",
  "description": "Detailed product description",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "email": "customer@example.com",
  "comment": "Special request",
  "customerId": "user_12345",
  "period": "monthly",
  "starsAmount": 50,
  "imageUrl": "https://example.com/product-image.jpg",
  "firstPeriodAmount": 50000,
  "trialPeriod": "seven_days"
}
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Product X",
  "description": "Detailed product description",
  "status": "paid",
  "email": "customer@example.com",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
  "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
  "createdAt": "2025-11-13T15:04:05Z",
  "comment": "Special request",
  "period": "onetime",
  "memberStatus": "active",
  "memberExpiresAt": "2025-12-13T15:04:05Z",
  "memberInTrial": true,
  "memberTrialStartedAt": "2025-12-13T15:04:05Z",
  "memberTrialEndsAt": "2025-12-20T15:04:05Z",
  "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
  "starsAmount": 0,
  "onlyStars": false,
  "firstPeriodAmount": 50000,
  "sendEmail": false,
  "image": {
    "id": 123,
    "path": "https://cdn.example.com/image.jpg",
    "thumbnail": "text",
    "width": 800,
    "height": 600,
    "fileType": "image"
  }
}

Get Shop Orders by Status

get

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).

Authorizations
Api-KeystringRequired

API key for authentication.

Query parameters
shopIdinteger · uint64Optional

ID of the shop to read orders from. Defaults to the oldest shop owned by the authenticated user.

Example: 1
statusstring · enumOptional

Filter by order status. When omitted and page is not provided, returns all statuses. When set to all or omitted with page, returns all orders.

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.

Example: paidPossible values:
pageinteger · min: 1Optional

Page number (1-based). When omitted, triggers the initial grouped load.

Example: 1
sizeinteger · min: 1 · max: 100Optional

Number of orders per page (default 20, max 100)

Default: 20Example: 20
dateFromstring · dateOptional

Start date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-01-01
dateTostring · dateOptional

End date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-12-31
Responses
200

Successful response

application/json
nextFromstringRequired

Next page number as string. Empty string if no more pages.

Example: 2
get/shop/orders_by_status
GET /api/v1/shop/orders_by_status HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "counts": {
    "all": 42,
    "pending": 5,
    "paid": 30,
    "failed": 7
  },
  "orders": {
    "all": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 100000,
        "currency": "rub",
        "title": "Product X",
        "status": "paid"
      }
    ],
    "pending": [],
    "paid": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 100000,
        "currency": "rub",
        "title": "Product X",
        "status": "paid"
      }
    ],
    "failed": []
  },
  "nextFrom": "2"
}

Get Shop Order

get

Returns full details of a specific shop order by its UUID. Includes member status and image. Only accessible by the shop owner.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Successful response

application/json
uuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

Shop ID this order belongs to

Example: 1
amountinteger · int64Required

Order amount in smallest currency units (cents/kopecks)

Example: 100000
currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:
titlestringRequired

Order title (max 100 UTF-16 characters)

Example: Product X
descriptionstringRequired

Order description (max 300 UTF-16 characters)

Example: Detailed product description
statusstring · enumRequired

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.

A card decline does not change the status — the order stays pending and payable.

Example: paidPossible values:
emailstring · emailOptional

Customer email (optional)

Example: customer@example.com
successUrlstring · uriRequired

Redirect URL on successful payment

Example: https://shop.com/success
failUrlstring · uriRequired

Redirect URL on failed payment

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Web URL for customer to complete payment in a browser. null for OnlyStars orders — they can only be paid inside Telegram via webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

Telegram WebApp payment URL for in-app payment

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Order creation timestamp in ISO 8601 format

Example: 2025-11-13T15:04:05Z
commentstringOptional

Optional comment for the order

Example: Special request
periodstring · enumRequired

Billing period for recurring orders

Example: onetimePossible values:
memberStatusstring · enumOptional

Recurring subscription status (only for recurring orders)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Recurring subscription expiration date in ISO 8601 format (only for recurring orders)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

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.

Example: true
memberTrialStartedAtstring · date-timeOptional

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.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

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.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Date of the last paid transaction in ISO 8601 format. Null if no transactions exist.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Fixed amount in Telegram Stars (0 if not set)

Example: 0
onlyStarsbooleanOptional

Whether this order only accepts Telegram Stars payment

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

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.

Example: 50000
sendEmailbooleanOptional

Whether a receipt email is sent to the buyer after successful payment (inherited from the shop at creation)

Example: false
get/shop/orders/{orderUuid}
GET /api/v1/shop/orders/{orderUuid} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Product X",
  "description": "Detailed product description",
  "status": "paid",
  "email": "customer@example.com",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
  "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
  "createdAt": "2025-11-13T15:04:05Z",
  "comment": "Special request",
  "period": "onetime",
  "memberStatus": "active",
  "memberExpiresAt": "2025-12-13T15:04:05Z",
  "memberInTrial": true,
  "memberTrialStartedAt": "2025-12-13T15:04:05Z",
  "memberTrialEndsAt": "2025-12-20T15:04:05Z",
  "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
  "starsAmount": 0,
  "onlyStars": false,
  "firstPeriodAmount": 50000,
  "sendEmail": false,
  "image": {
    "id": 123,
    "path": "https://cdn.example.com/image.jpg",
    "thumbnail": "text",
    "width": 800,
    "height": 600,
    "fileType": "image"
  }
}

Get Shop Order Status

get

Returns the current status of a specific shop order by its UUID. Only accessible by the shop owner.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Successful response

application/json
statusstring · enumRequired

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.

Example: paidPossible values:
get/shop/orders/{orderUuid}/status
GET /api/v1/shop/orders/{orderUuid}/status HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "status": "paid"
}

Cancel Recurring Shop Order

post

Cancels a recurring shop order subscription. Only accessible by the shop owner or authorized managers.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Order cancelled successfully

application/json
successbooleanRequired

Whether the operation was successful

Example: true
messagestringRequired

Success message

Example: recurring order cancelled
post/shop/orders/{orderUuid}/cancel
POST /api/v1/shop/orders/{orderUuid}/cancel HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "recurring order cancelled"
}

Get Shop Order Transactions

get

Returns a paginated list of transactions for a specific shop order. Only accessible by the shop owner or authorized managers.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
Query parameters
startFromintegerOptional

Pagination offset (number of records to skip)

Default: 0Example: 0
Responses
200

Successful response

application/json
nextFromstringRequired

Offset for the next page. Empty string if no more pages

Example: 20
get/shop/orders/{orderUuid}/transactions
GET /api/v1/shop/orders/{orderUuid}/transactions HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "transactions": [
    {
      "id": 12345,
      "type": "shop_order_sell",
      "objectId": 100,
      "amount": 1000,
      "currency": "rub",
      "createdAt": 1731510245,
      "serviceFee": 80,
      "total": 920,
      "paymentMethod": "bank_card",
      "isRefunded": false,
      "isRefundable": true,
      "isRecurring": false,
      "shopOrder": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Product X",
        "description": "Detailed product description",
        "amount": 1000,
        "currency": "eur",
        "status": "paid",
        "email": "customer@example.com",
        "successUrl": "https://shop.com/success",
        "failUrl": "https://shop.com/fail",
        "createdAt": 1731510245,
        "comment": "Special request",
        "period": "onetime",
        "shopName": "My Shop",
        "starsAmount": 0,
        "onlyStars": false
      }
    }
  ],
  "nextFrom": "20"
}

Refund Shop Order Transaction

post

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.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
txIdinteger · uint64Required

Transaction ID (must be a sell transaction)

Example: 12345
Responses
200

Refund initiated successfully

application/json
successbooleanRequired

Whether the operation was successful

Example: true
messagestringRequired

Success message

Example: refund initiated
statusstring · enumRequired

Refund status

Example: initiatedPossible values:
post/shop/orders/{orderUuid}/transactions/{txId}/refund
POST /api/v1/shop/orders/{orderUuid}/transactions/{txId}/refund HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "refund initiated",
  "status": "initiated"
}

Resend Shop Order Webhook

post

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.

Authorizations
Api-KeystringRequired

API key for authentication.

Path parameters
orderUuidstring · uuidRequired

Order UUID

Example: 550e8400-e29b-41d4-a716-446655440000
Body
eventstring · enumRequired

Webhook event type to resend

Example: shop_order_charge_successPossible values:
Responses
200

Resend scheduled successfully

application/json
successbooleanRequired

Whether the resend was scheduled

Example: true
post/shop/orders/{orderUuid}/webhooks/resend
POST /api/v1/shop/orders/{orderUuid}/webhooks/resend HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "event": "shop_order_charge_success"
}
{
  "success": true
}
PreviousShop API
NextWebhooks

Last updated