Dashboard
APIPayment History | Subscription Bot API
api.botsubscription.com
GET/v1/endpoint
AuthenticationBearer
Token
Stays in this tab. Required for this endpoint — the value below is what gets sent.
Examples
curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

Project Payment History

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.

limitinteger

Page size from 1 to 100; default 10.

offsetinteger

Nonnegative offset; default 0.

Reconcile subscription payments

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.

Use payment-request details to reconcile an individual checkout, or subscription details to check recurring billing state.

Follow the decimal amount rules when processing monetary values.

Last updated: