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:

401

Unauthorized (invalid API key)

application/json

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:

401

Unauthorized (invalid API key)

application/json

404

Shop not found

application/json

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.

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

401

Unauthorized (invalid API key)

application/json

404

Shop not found

application/json

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

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

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

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Access denied (shopId belongs to another user)

application/json

404

Shop not found

application/json

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:

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.
Paginated "all" (page provided, no status or status=all): Returns a specific page of all orders under the all key.
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

400

Bad request (invalid status parameter)

application/json

401

Unauthorized (invalid API key)

application/json

404

Shop not found

application/json

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

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

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

401

Unauthorized (invalid API key)

application/json

403

Forbidden (order belongs to another shop)

application/json

404

Order or shop not found

application/json

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:

401

Unauthorized (invalid API key)

application/json

403

Forbidden (order belongs to another shop)

application/json

404

Order or shop not found

application/json

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

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order, shop, or recurring subscription not found

application/json

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

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order or shop not found

application/json

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:

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order, shop, or transaction not found

application/json

500

Internal server error (refund processing failed)

application/json

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

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order, shop, or a webhook of this event type not found

application/json

429

Rate limit exceeded - one resend per event type per order per minute

application/json

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 11 days ago