Read a unified history for your Telegram subscription bot or Discord subscription bot, including completed purchases, balance top-ups, refunds, and adjustments.
GET/v2/projects/{project_id}/payment-history
Authorization
Bearer API KeyRequired
API key scope:payment-history:read for restricted keys, which must also supply user_id. Unrestricted project keys can omit it to read the whole project. Restricted keys cannot request all=true.
Path Parameters
project_idstringrequired
Project UUID.
Query Parameters
user_idstring
External Telegram user ID or Discord snowflake as a string. Required for restricted keys.
allboolean
Request all users; unrestricted keys only. Cannot combine true with user_id.
date_fromstring
Inclusive performed_at lower bound: UTC ISO with milliseconds, 10-digit Unix seconds, or 13-digit Unix milliseconds.
date_tostring
Inclusive performed_at upper bound in the same formats as date_from.
Results sort by performed_at descending, then id descending. The response returns total without echoing pagination parameters. A balance-funded purchase appears once as an invoice payment.
item_type values are paymentRequest or balanceTransaction. Directions are invoice, balanceTopUp, refund, and adjustment; preserve their case. Adjustment amounts can be signed. Other amounts are nonnegative decimal strings. Stored decimal scale is preserved; do not assume two decimal places.
Enriched project rows include the nullable payment-reference, plan, subscription, membership, coupon, and settlement fields shown in the examples. Adjustment details are null. Provider identity can survive account removal, or be legacy-unmapped when it cannot be recovered. Purchased duration uses its stored value where available, otherwise the current plan's duration; it need not be normalized, and "0" means lifetime.