API

Get Started

As a member of the TGmembership family, you can use the API to automate your memberships' management. For example, you can connect your Telegram bot directly to your website and give your customers access to your Telegram chats automatically.

Before you can use the TGmembership API, you must have a bot and an API key created. If you don't have one yet, create your Telegram bot and connect it to TGmembership.

Generate API Endpoint

To learn how to generate an API key, please refer to our guide on creating an API key.

Authentication

The TGmembership API uses API keys to authenticate requests. You can view and manage your API key from your bot's settings menu.

All queries to the TGmembership API must be served over HTTPS, using GET, POST or DELETE HTTP methods, and need to be presented in this form: https://api.tgmembership.com/{{VERSION}}/bot{{BOT_ID}}/{{API_KEY}}/{{METHOD_NAME}}

Calls made over plain HTTP will fail. API requests without authentication will also fail. All methods in the TGmembership API are case-insensitive.

The response contains a JSON object, which always has a Boolean field "ok", Integer field "code" and may have an optional String field "description" with a human-readable description of the result. If "ok" equals true, the request was successful and the result of the query can be found in the "result" field. In case of an unsuccessful request, "ok" equals false and the error is explained in the "description".

[POST] /affiliate

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/affiliate

This API method allows you to register new affiliates remotely.

Request Body

Name Type Description

Name	Type	Description
`member_id`*	Integer, required	The unique identifier of a member who has previously interacted with the bot and has not blocked it.
`affiliate_id`	String, optional	A user-chosen string that identifies the affiliate. It must start with a letter, be at least 3 characters long, no more than 12, and be unique (not used by anyone else).

member_id*

Integer, required

The unique identifier of a member who has previously interacted with the bot and has not blocked it.

affiliate_id

String, optional

A user-chosen string that identifies the affiliate. It must start with a letter, be at least 3 characters long, no more than 12, and be unique (not used by anyone else).

{
    "ok": true,
    "request_id": "123456789",
    "method": "POST",
    "path": "/affiliate",
    "code": 200,
    "result": {
        "affiliate_id": "abcd123",
        "affiliate_link": "https://t.me/tgmembership_demobot?start=r_abcd123"
    }

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/affiliate",
    "code": 400,
    "description": "Bad request: 'affiliate_id' must match pattern \"^[a-zA-Z][a-zA-Z0-9]{2,19}$\""
}

Reason: The affiliate_id provided is invalid.
Solution: The affiliate_id must start with a letter and be 3 to 20 characters long, consisting of letters and numbers only.

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/affiliate",
    "code": 401,
    "description": "Unauthorized: Affiliate API is not available for this bot"
}

Reason: The affiliate add-on hasn't been installed in this bot.
Solution: Install the affiliate add-on using the /affiliate command in your bot on Telegram.

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/affiliate",
    "code": 404,
    "description": "Not Found: Member with this ID has not been found."
}

Reason: The member_id provided does not belong to someone who has previously interacted with the bot or they have blocked the bot.
Solution: Ensure the member_id is correct and belongs to someone who has interacted with the bot.

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/affiliate",
    "code": 409,
    "description": "Conflict: Affiliate with this ID already exists."
}

Reason: The affiliate_id provided is already in use by another affiliate.
Solution: Provide a different affiliate_id that is unique.

[POST] /bot

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/bot

This endpoint allows you to register a new bot. The owner of the bot that owns the API key used for this call will also be registered as the owner and billpayer for the new bot.

Body

Name Type Description

Name	Type	Description
`bot_token`*	String, required	The API token generated from @BotFather in Telegram.

bot_token*

String, required

The API token generated from @BotFather in Telegram.

Response

{
  "request_id": "123456789",
  "method": "POST",
  "path": "/bot",
  "code": 201,
  "result": {
    "bot_id": 1347378140,
    "bot_username": "tgmembership_demobot",
    "api_key": "abcd123"
  }
}

{
  "ok": false,
  "request_id": "123456789",
  "method": "POST",
  "path": "/bot",
  "code": 402,
  "description": "Payment Required: You have unpaid bills."
}

Reason: The billpayer (owner of the bot) has one or more unpaid bills. New bots cannot be created until all existing bills are paid.
Solution: Open TGmembership_Bot in Telegram and pay any outstanding bills.

{
  "ok": false,
  "request_id": "123456789",
  "method": "POST",
  "path": "/bot",
  "code": 409,
  "description": "Conflict: Bot with this ID is already installed."
}

Reason: This bot is already registered with TGmembership.
Solution: N/A

[GET] /coupons

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/coupons

This endpoint retrieves the list of coupons available in the bot.

Response

{
  "request_id": "123456789",
  "method": "GET",
  "path": "/coupons",
  "code": 200,
  "result": [
    {
      "name": "discountcode",
      "amount": "0",
      "percent": "10",
      "min_amount": "0",
      "max_amount": "0",
      "uses": 0,
      "used": 0,
      "plans": [
        14
      ],
      "newcomers": false,
      "singleuse": false,
      "invitee_only": false,
      "auto_apply": false,
      "enabled": true
    },
    {
      "name": "HJTPS3",
      "amount": "0",
      "percent": "11",
      "min_amount": "0",
      "max_amount": "0",
      "uses": 0,
      "used": 0,
      "payment_gateways": [
        "paypal"
      ],
      "plans": [
        11,
        14,
        18
      ],
      "revenue": {
        "direction": "above",
        "amount": "10",
        "currency": "USD"
      },
      "newcomers": false,
      "singleuse": true,
      "invitee_only": true,
      "auto_apply": true,
      "enabled": true
    }
  ]
}

{
  "ok": false,
  "request_id": "123456789",
  "method": "GET",
  "path": "/coupons",
  "code": 404,
  "description": "Not Found: There are no coupons to display"
}

Reason: No coupons are available in the bot's database.
Solution: Ensure that there are coupons created and available in the bot.

[GET] /members

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/members

Fetch all subscribers

Query Parameters

Name Type Description

Name	Type	Description
`member_id`	Integer, optional	The unique identifier of a member who has previously interacted with the bot and has not blocked it.
`plan_id`	Integer, optional	The unique identifier of an existing plan. Must be a positive number.
`project_id`	Integer, optional	The unique identifier of an existing project. Must be a positive number.
`limit`	Integer, optional	Limits the number of results returned by the API. Must be an integer between 1 and 1000. Default is 100.
`offset`	Integer, optional	Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

member_id

Integer, optional

The unique identifier of a member who has previously interacted with the bot and has not blocked it.

plan_id

Integer, optional

The unique identifier of an existing plan. Must be a positive number.

project_id

Integer, optional

The unique identifier of an existing project. Must be a positive number.

limit

Integer, optional

Limits the number of results returned by the API. Must be an integer between 1 and 1000. Default is 100.

offset

Integer, optional

Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/members",
  "code": 200,
  "result": [
    {
      "member_id": 1111111111,
      "plan_id": 1,
      "project_id": 1,
      "membership": {
        "start": 1721137290,
        "end": 1721742090
      }
    },
    {
      "member_id": 2222222222,
      "plan_id": 14,
      "project_id": 2,
      "membership": {
        "start": 1721137296,
        "end": 1721223696
      }
    },
    {
      "member_id": 1111111111,
      "plan_id": 18,
      "project_id": 3,
      "membership": {
        "start": 1721137382,
        "end": 1721310182
      }
    }
  ]
}

[POST] /members/accessToken

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/members/accessToken

This API method creates a unique access token that allows users to activate memberships without payment. For more information on access tokens, please check out our help article.

Request Body

Name Type Description

Name	Type	Description
`plan_id`*	Integer, required	The unique identifier of an existing plan. Must be a positive number.
`member_id`	Integer, optional	The unique identifier of a member who has previously interacted with the bot and has not blocked it.

plan_id*

Integer, required

The unique identifier of an existing plan. Must be a positive number.

member_id

Integer, optional

The unique identifier of a member who has previously interacted with the bot and has not blocked it.

Response

{
    "ok": true,
    "request_id": "123456789",
    "method": "POST",
    "path": "/members/access_token",
    "code": 201,
    "result": {
        "bot_username": "tgmembership_demobot",
        "access_token": "abcd123",
        "link": "https://t.me/tgmembership_demobot?start=accesstoken_abcd123"
    }
}

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/members/access_token",
    "code": 401,
    "description": "Unauthorized: Access tokens are not available for this bot."
}

Reason: One reason could be that you haven't installed a payment method in your bot, or it is in test mode.
Solution: Open Telegram, open your bot, type /settings -> Test mode and switch it off. Then, go to /settings -> Payment Methods and install a payment method.

Reason: Another reason, applicable if you're on the Pay As You Go 7% billing plan, could be a violation of our Acceptable Use Policy.
Solution: After accepting a certain number of real payments, you may be eligible to have access tokens reactivated. This may take some time. Alternatively, you can upgrade your plan to any of our Pay Monthly options, which offer unlimited access token usage for a fixed monthly fee.

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/members/access_token",
    "code": 404,
    "description": "Not Found: Member with this ID has not been found"
}

Reason: The member_id provided is invalid, or belongs to someone who hasn't previously interacted with the bot, or the person has blocked the bot.
Solution: Double-check the member_id provided. Ensure it's correct and that the user has previously interacted with the bot and hasn't blocked it.

[GET] /orders/:order_key

GET /orders/:order_key

This endpoint fetches a specific order based on the provided order key.

Path Parameters

Name Type Description

Name	Type	Description
`order_key`	String, required	The unique key identifying the specific order to be fetched.

order_key

String, required

The unique key identifying the specific order to be fetched.

Response

{
  "request_id": "123456789",
  "method": "GET",
  "path": "/orders/ABCD123",
  "code": 200,
  "result": {
    "order_key": "ABCD123",
    "member_id": 0,
    "member_name": "John Doe",
    "member_email": "john@doe.com",
    "payment_gateway": "stripe",
    "order_status": "PENDING",
    "order_date": 1721159920,
    "plan_id": 11,
    "project_id": 1
  }
}

{
  "ok": false,
  "request_id": "123456789",
  "method": "GET",
  "path": "/orders/ABCD123",
  "code": 404,
  "description": "Not Found: The requested resource could not be found."
}

Reason: The ID provided doesn't match any orders in your bot's database.
Solution: Double-check the order_key provided.

[GET] /orders

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/orders

This endpoint returns the orders in the bot. If no query parameters are provided, it will return the last 100 orders in descending order. Query parameters allow customisation of the returned list.

Query Parameters

Name Type Description

Name	Type	Description
`member_id`	Integer, optional	The unique identifier of a member who has previously interacted with the bot and has not blocked it.
`plan_id`	Integer, optional	The unique identifier of an existing plan. Must be a positive number.
`project_id`	Integer, optional	The unique identifier of an existing project. Must be a positive number.
`order_status`	String, optional	The status of the order.
`currency`	String, optional	Specifies the currency for converting the amounts.
`limit`	Integer, optional	Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.
`offset`	Integer, optional	Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

member_id

Integer, optional

The unique identifier of a member who has previously interacted with the bot and has not blocked it.

plan_id

Integer, optional

The unique identifier of an existing plan. Must be a positive number.

project_id

Integer, optional

The unique identifier of an existing project. Must be a positive number.

order_status

String, optional

The status of the order.

currency

String, optional

Specifies the currency for converting the amounts.

limit

Integer, optional

Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.

offset

Integer, optional

Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

Response

{
  "request_id": "123456789",
  "method": "GET",
  "path": "/orders?currency=usd",
  "code": 200,
  "result": [
    {
      "order_key": "66804997RC5418150",
      "order_type": 1,
      "order_date": 1721285697,
      "order_status": "PENDING",
      "member_id": 1111111111,
      "member_name": "John Doe",
      "plan_id": 20,
      "plan_name": "EUR Demo Plan",
      "project_id": 0,
      "payment_gateway": "PayPal",
      "amount": "1.344882",
      "currency": "USD",
      "formatted": "$1.34"
    },
    {
      "order_key": "TGM_20240718_360140305",
      "order_type": 1,
      "order_date": 1721276234,
      "order_status": "PENDING",
      "member_id": 2222222222,
      "member_name": "Mark Moe",
      "plan_id": 38,
      "plan_name": "RUB Demo Plan",
      "project_id": 0,
      "payment_gateway": "Telegram Pay",
      "amount": "11.35291",
      "currency": "USD",
      "formatted": "$11.35"
    },
    {
      "order_key": "d2615671-b946-4e68-ebd8-6714a042079a",
      "order_type": 1,
      "order_date": 1721255592,
      "order_status": "COMPLETED",
      "member_id": 3333333333,
      "member_name": "Sam Soe",
      "plan_id": 20,
      "plan_name": "EUR Demo Plan",
      "project_id": 0,
      "payment_gateway": "Crypto (Crypto.Com)",
      "amount": "1.344882",
      "currency": "USD",
      "formatted": "$1.34"
    },
    {
      "order_key": "cs_test_abcd123",
      "order_type": 1,
      "order_date": 1721196809,
      "order_status": "COMPLETED",
      "member_id": 4444444444,
      "member_name": "Jane Doe",
      "plan_id": 20,
      "plan_name": "EUR Demo Plan",
      "project_id": 0,
      "payment_gateway": "Credit / Debit card (Stripe)",
      "amount": "1.344882",
      "currency": "USD",
      "formatted": "$1.34"
    },
    {
      "order_key": "2DG51012HU4265914",
      "order_type": 1,
      "order_date": 1721196532,
      "order_status": "PENDING",
      "member_id": 5555555555,
      "member_name": "Tom",
      "plan_id": 25,
      "plan_name": "BRL Demo Plan",
      "project_id": 0,
      "payment_gateway": "PayPal",
      "amount": "9.25856208",
      "currency": "USD",
      "formatted": "$9.26"
    }
  ]
}

[POST] /orders

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/orders

Create a new invoice

Request Body

Name Type Description

Name	Type	Description
`plan_id`*	Integer, required	The unique identifier of an existing plan. Must be a positive number.
`payment_gateway`*	String, required	Choose the payment method for this invoice, such as "PayPal," "Stripe," "CryptoNoKYC," or any other installed method. The selected method must be installed in the bot. If unsure about available options, retrieve a list of installed payment methods using the GET /paymentMethods API request.
`member_id`	Integer, optional	The unique identifier of a member who has previously interacted with the bot and has not blocked it.
`email`	String, conditional	Required for specific payment methods, such as Paystack. Otherwise, this parameter is optional.
`token`	String, conditional	Needed for specific payment methods, such as crypto. For BinancePay, pass the token name, e.g., "USDT." For CryptoNoKYC, include both the token name and the network, formatted as "TOKEN.NETWORK," e.g., "USDT.MATIC."
`return_url`	String, optional	The URL to which the user will be redirected after successful payment. If not provided, the default TGmembership return URL will be used. Applicable only for payment methods that support custom return URLs, such as Stripe.
`cancel_url`	String, optional	Similar to `return_url`, but used if the payment process is canceled.

plan_id*

Integer, required

The unique identifier of an existing plan. Must be a positive number.

payment_gateway*

String, required

Choose the payment method for this invoice, such as "PayPal," "Stripe," "CryptoNoKYC," or any other installed method. The selected method must be installed in the bot. If unsure about available options, retrieve a list of installed payment methods using the GET /paymentMethods API request.

member_id

Integer, optional

The unique identifier of a member who has previously interacted with the bot and has not blocked it.

email

String, conditional

Required for specific payment methods, such as Paystack. Otherwise, this parameter is optional.

token

String, conditional

Needed for specific payment methods, such as crypto. For BinancePay, pass the token name, e.g., "USDT." For CryptoNoKYC, include both the token name and the network, formatted as "TOKEN.NETWORK," e.g., "USDT.MATIC."

return_url

String, optional

The URL to which the user will be redirected after successful payment. If not provided, the default TGmembership return URL will be used. Applicable only for payment methods that support custom return URLs, such as Stripe.

cancel_url

String, optional

Similar to return_url, but used if the payment process is canceled.

Response

{
    "ok": true,
    "request_id": "123456789",
    "method": "POST",
    "path": "/orders",
    "code": 200,
    "result": {
        "order_key": "TGM-1234567890-20240716-abcd1234",
        "amount": "3",
        "currency": "EUR",
        "checkout_url": "https://example.com"
    }
}

{
    "ok": true,
    "request_id": "123456789",
    "method": "POST",
    "path": "/orders",
    "code": 200,
    "result": {
        "order_key": "abcd123",
        "amount": "3.272",
        "currency": "USDT",
        "address": "0xabcdefghijklmnopqrstuvwxyz0123456789",
        "network": "matic",
        "qr_link": "https://example.com/qr.png",
        "expire": 1721181520
    }
}

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/orders",
    "code": 400,
    "description": "Payment gateway 'xyz' is not installed"
}

Reason: The payment gateway you are trying to use to create an order is not installed in your bot.
Solution: Open your bot, type /settings -> Payment Methods and install the payment method.

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/orders",
    "code": 400,
    "description": "Pre-checkout data is missing or invalid. Token needs to be selected."
}

Reason: You're trying to create a crypto order without providing the token/network for the payment.
Solution: Review the token parameter; it is required when using crypto payments. Ensure the token and network are correctly specified.

[GET] /orders/count

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/orders/count

This endpoint returns a list of daily, monthly, or yearly revenue and sales data.

Query Parameters

Name Type Description

Name	Type	Description
`interval_unit`	Enum, optional	Specifies the unit of time for the interval. Valid values are 'day', 'month', or 'year'. Default is 'month'.
`interval_count`	Integer, optional	Specifies the number of intervals. Must be an integer greater than or equal to 1. Default is 1.
`currency`	Enum, optional	Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set. Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

interval_unit

Enum, optional

Specifies the unit of time for the interval. Valid values are 'day', 'month', or 'year'. Default is 'month'.

interval_count

Integer, optional

Specifies the number of intervals. Must be an integer greater than or equal to 1. Default is 1.

currency

Enum, optional

Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set.

Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/orders/count?interval_unit=month&interval_count=3&currency=usd",
  "code": 200,
  "result": [
    {
      "period": "2024-07",
      "revenue": "38.0371384",
      "currency": "USD",
      "formatted": "$38.04",
      "sales": 10
    },
    {
      "period": "2024-06",
      "revenue": "440.66793845",
      "currency": "USD",
      "formatted": "$440.67",
      "sales": 12
    },
    {
      "period": "2024-05",
      "revenue": "234.82823044",
      "currency": "USD",
      "formatted": "$234.83",
      "sales": 9
    }
  ]
}

[GET] /paymentMethods

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/paymentMethods

Check your bot's payment methods

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/payment_methods",
  "code": 200,
  "result": [
    {
      "name": "cryptonokyc",
      "display_name": "Crypto (No KYC)",
      "supports_recurring": false,
      "requires_email": false,
      "tokens": [
        {
          "token": "BTC.LN",
          "display_name": "Bitcoin (Lightning)"
        },
        {
          "token": "BUSD.BEP20",
          "display_name": "BUSD (BEP20)"
        },
        {
          "token": "ETH.BASE",
          "display_name": "Ethereum (BASE)"
        },
        {
          "token": "BTC.BTC",
          "display_name": "Bitcoin"
        },
        {
          "token": "DOGE.BEP20",
          "display_name": "DOGE (BEP20)"
        },
        {
          "token": "BCH.BCH",
          "display_name": "Bitcoin Cash"
        },
        {
          "token": "LTC.LTC",
          "display_name": "Litecoin"
        }
      ]
    },
    {
      "name": "paypal",
      "display_name": "PayPal",
      "supports_recurring": true,
      "requires_email": false
    },
    {
      "name": "paystack",
      "display_name": "Paystack",
      "supports_recurring": false,
      "requires_email": true
    },
    {
      "name": "reepay",
      "display_name": "Billwerk+",
      "supports_recurring": true,
      "requires_email": true
    },
    {
      "name": "stripe",
      "display_name": "Credit / Debit card (Stripe)",
      "supports_recurring": true,
      "requires_email": false
    },
    {
      "name": "telegram_stars",
      "display_name": "Telegram Stars",
      "supports_recurring": false,
      "requires_email": false
    },
    {
      "name": "yookassa",
      "display_name": "YooKassa",
      "supports_recurring": false,
      "requires_email": true
    }
  ]
}

[GET] /paymentMethods/report

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/paymentMethods/report

This API method returns a list of the most popular payment methods used for sales, along with the number of sales made using each payment method.

Query Parameters

Name Type Description

Name	Type	Description
`currency`	String, optional	Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set. Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

currency

String, optional

Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set.

Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/payment_methods/report",
  "code": 200,
  "result": [
    {
      "name": "cryptocom",
      "display_name": "Crypto (Crypto.Com)",
      "revenue": "2412.0767644",
      "currency": "EUR",
      "formatted": "2 412,08€",
      "sales": 69
    },
    {
      "name": "stripe",
      "display_name": "Credit / Debit card (Stripe)",
      "revenue": "2165.20800147",
      "currency": "EUR",
      "formatted": "2 165,21€",
      "sales": 85
    },
    {
      "name": "telegram",
      "display_name": "Telegram Pay",
      "revenue": "762.50008054",
      "currency": "EUR",
      "formatted": "762,50€",
      "sales": 14
    },
    {
      "name": "authorizenet",
      "display_name": "AuthorizeNet",
      "revenue": "93.50875536",
      "currency": "EUR",
      "formatted": "93,51€",
      "sales": 2
    },
    {
      "name": "paypal",
      "display_name": "PayPal",
      "revenue": "74.01085615",
      "currency": "EUR",
      "formatted": "74,01€",
      "sales": 22
    },
    {
      "name": "revolut",
      "display_name": "Revolut",
      "revenue": "68.1283877",
      "currency": "EUR",
      "formatted": "68,13€",
      "sales": 4
    },
    {
      "name": "yookassa",
      "display_name": "YooKassa",
      "revenue": "32.11025898",
      "currency": "EUR",
      "formatted": "32,11€",
      "sales": 5
    },
    {
      "name": "gocardless",
      "display_name": "GoCardless",
      "revenue": "5.94919385",
      "currency": "EUR",
      "formatted": "5,95€",
      "sales": 1
    }
  ]
}

[GET] /plans

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/plans

This method returns a list of all available plans, including their names, prices, and durations. It provides more detailed information about each plan and can be used for various purposes.

Query Parameters

Name Type Description

Name	Type	Description
`plan_id`	Integer, optional	The unique identifier of an existing plan. Must be a positive number.
`project_id`	Integer, optional	The unique identifier of an existing project. Must be a positive number.
`limit`	Integer, optional	Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.
`offset`	Integer, optional	Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

plan_id

Integer, optional

The unique identifier of an existing plan. Must be a positive number.

project_id

Integer, optional

The unique identifier of an existing project. Must be a positive number.

limit

Integer, optional

Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.

offset

Integer, optional

Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/plans",
  "code": 200,
  "result": [
    {
      "plan_id": 20,
      "plan_name": "EUR Demo Plan",
      "duration": "2 days",
      "price": "1.23",
      "currency": "EUR",
      "options": {
        "recurring": false,
        "newcomers": 0,
        "singleuse": 0,
        "token_only": false,
        "credit_only": false,
        "invitee_only": 0,
        "is_hidden": false
      },
      "max_customers": 0,
      "sort_order": 100,
      "enabled": true
    },
    {
      "plan_id": 19,
      "plan_name": "USD Demo Plan",
      "duration": "1 year",
      "price": "99.99",
      "currency": "USD",
      "options": {
        "recurring": false,
        "newcomers": 0,
        "singleuse": 0,
        "token_only": false,
        "credit_only": false,
        "invitee_only": 0,
        "is_hidden": false
      },
      "max_customers": 0,
      "sort_order": 90,
      "enabled": true
    }
  ]
}

{
  "ok": false,
  "request_id": "123456789",
  "method": "GET",
  "path": "/plans",
  "description": "No plans found"
}

Reason: No plans are available in the bot's database.
Solution: Ensure that there are plans created and available in the bot.

[POST] /plans

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/plans

This endpoint allows you to create a new subscription plan in the bot.

Request Body

Name Type Description

Name	Type	Description
`plan_name`*	String, required	The name of the subscription plan. The name must be between 3 and 24 characters long, and start with a letter.
`plan_duration`*	String, required	The duration of the subscription plan. This is typically specified in a format like "1 month" or "1 year".
`plan_price`*	String, required	The price of the subscription plan. This should include the amount without currency code.
`plan_currency`*	String, required	The currency in which the plan price is specified, e.g., "USD".
`plan_trial`	String, optional	The duration of the trial period for the subscription plan, if any. This is typically specified in a format like "1 month" or "1 year".
`plan_project_id`	Integer, optional	The project ID associated with the subscription plan. This must be a positive integer.
`options`	Object, optional	A set of additional options for the subscription plan.

plan_name*

String, required

The name of the subscription plan. The name must be between 3 and 24 characters long, and start with a letter.

plan_duration*

String, required

The duration of the subscription plan. This is typically specified in a format like "1 month" or "1 year".

plan_price*

String, required

The price of the subscription plan. This should include the amount without currency code.

plan_currency*

String, required

The currency in which the plan price is specified, e.g., "USD".

plan_trial

String, optional

The duration of the trial period for the subscription plan, if any. This is typically specified in a format like "1 month" or "1 year".

plan_project_id

Integer, optional

The project ID associated with the subscription plan. This must be a positive integer.

options

Object, optional

A set of additional options for the subscription plan.

Options Object

Name Type Description

Name	Type	Description
`recurring`	Boolean, optional	Indicates whether the subscription plan is recurring.
`newcomers`	Integer, optional	Specifies the availability of the plan based on user status: 0: The plan is available to everyone. 1: The plan is available to newcomers only. 2: The plan is available to returning users (those who previously held a membership or currently hold one).
`singleuse`	Integer, optional	Specifies the purchase limitations for the plan: 0: The plan can be purchased multiple times by a user. 1: The plan can be purchased only one time by a specific user. 2: The plan can be purchased only if the user currently holds a membership. 3: The plan can be purchased only if the user had a membership before but does not currently have an active one.
`token_only`	Boolean, optional	Indicates whether the plan is available for token payment only.
`credit_only`	Boolean, optional	Indicates whether the plan is available for credit payment only.
`invitee_only`	Integer, optional	Specifies the availability of the plan based on invitation status: 0: Everyone can purchase this plan. 1: Only users invited by an affiliate can purchase this plan. 2: Only users who haven't been invited by an affiliate can purchase this plan.

recurring

Boolean, optional

Indicates whether the subscription plan is recurring.

newcomers

Integer, optional

Specifies the availability of the plan based on user status:

0: The plan is available to everyone.
1: The plan is available to newcomers only.
2: The plan is available to returning users (those who previously held a membership or currently hold one).

singleuse

Integer, optional

Specifies the purchase limitations for the plan:

0: The plan can be purchased multiple times by a user.

1: The plan can be purchased only one time by a specific user.
2: The plan can be purchased only if the user currently holds a membership.
3: The plan can be purchased only if the user had a membership before but does not currently have an active one.

token_only

Boolean, optional

Indicates whether the plan is available for token payment only.

credit_only

Boolean, optional

Indicates whether the plan is available for credit payment only.

invitee_only

Integer, optional

Specifies the availability of the plan based on invitation status:

0: Everyone can purchase this plan.
1: Only users invited by an affiliate can purchase this plan.
2: Only users who haven't been invited by an affiliate can purchase this plan.

Response

{
  "request_id": "123456789",
  "method": "POST",
  "path": "/plans",
  "code": 201,
  "result": {
    "plan_id": 77,
    "plan_name": "Name of the plan",
    "duration": "1 week",
    "price": "100",
    "currency": "USD",
    "options": {
      "recurring": false,
      "newcomers": 0,
      "singleuse": 0,
      "token_only": false,
      "credit_only": false,
      "invitee_only": 0,
      "is_hidden": false
    },
    "max_customers": 0,
    "sort_order": 0,
    "enabled": true
  }
}

[GET] /plans/report

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/plans/report

This API method returns the revenue and number of sales for each subscription plan offered by your service on a monthly basis for the last 6 months.

Query Parameters

Name Type Description

Name	Type	Description
`currency`	String, optional	Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set. Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

currency

String, optional

Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set.

Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/plans/report",
  "code": 200,
  "result": [
    {
      "plan_id": 19,
      "plan_name": "USD Demo Plan",
      "revenue": "551.23244979",
      "currency": "EUR",
      "formatted": "551,23€",
      "sales": 7,
      "breakdown": [
        {
          "period": "2024-06",
          "revenue": "89.8184",
          "currency": "EUR",
          "formatted": "89,82€",
          "sales": 1
        },
        {
          "period": "2024-06",
          "revenue": "399.96",
          "currency": "EUR",
          "formatted": "399,96€",
          "sales": 4
        },
        {
          "period": "2024-05",
          "revenue": "199.98",
          "currency": "EUR",
          "formatted": "199,98€",
          "sales": 2
        }
      ]
    },
    {
      "plan_id": 21,
      "plan_name": "GBP Demo Plan",
      "revenue": "35.62931162",
      "currency": "EUR",
      "formatted": "35,63€",
      "sales": 6,
      "breakdown": [
        {
          "period": "2024-07",
          "revenue": "5",
          "currency": "EUR",
          "formatted": "5,00€",
          "sales": 1
        },
        {
          "period": "2024-06",
          "revenue": "5",
          "currency": "EUR",
          "formatted": "5,00€",
          "sales": 1
        },
        {
          "period": "2024-06",
          "revenue": "568.80310825",
          "currency": "EUR",
          "formatted": "568,80€",
          "sales": 1
        },
        {
          "period": "2024-05",
          "revenue": "15",
          "currency": "EUR",
          "formatted": "15,00€",
          "sales": 3
        }
      ]
    },
    {
      "plan_id": 38,
      "plan_name": "RUB Demo Plan",
      "revenue": "31.05438",
      "currency": "EUR",
      "formatted": "31,05€",
      "sales": 3,
      "breakdown": [
        {
          "period": "2024-06",
          "revenue": "2000",
          "currency": "EUR",
          "formatted": "2 000,00€",
          "sales": 2
        },
        {
          "period": "2024-05",
          "revenue": "1000",
          "currency": "EUR",
          "formatted": "1 000,00€",
          "sales": 1
        }
      ]
    },
    {
      "plan_id": 25,
      "plan_name": "BRL Demo Plan",
      "revenue": "17.00913401",
      "currency": "EUR",
      "formatted": "17,01€",
      "sales": 2,
      "breakdown": [
        {
          "period": "2024-07",
          "revenue": "100.74",
          "currency": "EUR",
          "formatted": "100,74€",
          "sales": 2
        }
      ]
    },
    {
      "plan_id": 20,
      "plan_name": "EUR Demo Plan",
      "revenue": "15.99",
      "currency": "EUR",
      "formatted": "15,99€",
      "sales": 13,
      "breakdown": [
        {
          "period": "2024-07",
          "revenue": "8.61",
          "currency": "EUR",
          "formatted": "8,61€",
          "sales": 7
        },
        {
          "period": "2024-06",
          "revenue": "3.69",
          "currency": "EUR",
          "formatted": "3,69€",
          "sales": 3
        },
        {
          "period": "2024-05",
          "revenue": "3.69",
          "currency": "EUR",
          "formatted": "3,69€",
          "sales": 3
        }
      ]
    },
    {
      "plan_id": 34,
      "plan_name": "Recurring Plan Demo",
      "revenue": "4.53981102",
      "currency": "EUR",
      "formatted": "4,54€",
      "sales": 1,
      "breakdown": [
        {
          "period": "2024-07",
          "revenue": "438.56721835",
          "currency": "EUR",
          "formatted": "438,57€",
          "sales": 1
        }
      ]
    }
  ]
}

[GET] /projects

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/projects

This endpoint retrieves the list of projects associated with the bot.

Name Type Description

Name	Type	Description
`project_id`	Integer, optional	The unique identifier of an existing project. Must be a positive number.
`limit`	Integer, optional	Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.
`offset`	Integer, optional	Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

project_id

Integer, optional

The unique identifier of an existing project. Must be a positive number.

limit

Integer, optional

Limits the number of results returned by the API. Must be an integer between 1 and 100. Default is 100.

offset

Integer, optional

Specifies the number of results to skip before starting to return results. Must be an integer greater than or equal to 0. Default is 0.

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/projects",
  "code": 200,
  "result": [
    {
      "project_id": 1,
      "project_name": "Basketball",
      "options": {
        "sort_order": 100,
        "is_hidden": false
      }
    },
    {
      "project_id": 9,
      "project_name": "Football",
      "options": {
        "is_hidden": false
      }
    },
    {
      "project_id": 10,
      "project_name": "Tennis",
      "options": {
        "is_hidden": true
      }
    }
  ]
}

{
  "ok": false,
  "request_id": "123456789",
  "method": "GET",
  "path": "/projects",
  "code": 401,
  "description": "Unauthorized: Projects API is not available for this bot"
}

Reason: The projects add-on hasn't been installed in this bot.
Solution: Install the projects add-on using the /projects command in your bot on Telegram.

{
  "ok": false,
  "request_id": "123456789",
  "method": "GET",
  "path": "/projects",
  "description": "No projects found"
}

Reason: No projects are available in the bot's database.
Solution: Ensure that there are projects created and available in the bot.

[GET] /revenue

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/revenue

This API method returns the total revenue generated and the number of sales for a specific period of time.

Query Parameters

Name Type Description

Name	Type	Description
`from`*	Integer, required	UNIX timestamp indicating the start of the time period for which revenue and sales data should be retrieved. Only data generated after this time will be included in the results. If not specified, the API will default to the earliest timestamp available.
`to`*	Integer, required	UNIX timestamp indicating the end of the time period for which revenue and sales data should be retrieved. Only data generated before this time will be included in the results. If not specified, the API will default to the latest timestamp available.
`currency`	String, optional	Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set. Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

from*

Integer, required

UNIX timestamp indicating the start of the time period for which revenue and sales data should be retrieved. Only data generated after this time will be included in the results. If not specified, the API will default to the earliest timestamp available.

to*

Integer, required

UNIX timestamp indicating the end of the time period for which revenue and sales data should be retrieved. Only data generated before this time will be included in the results. If not specified, the API will default to the latest timestamp available.

currency

String, optional

Specifies the currency for the revenue data. If not provided, the preferred currency for the bot will be used, or 'eur' if no preferred currency is set.

Valid values are 'usd', 'eur', 'gbp', 'cad', 'aud', 'nzd', 'jpy', 'cny', 'rub', 'brl', 'inr', 'try', 'btc'

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/revenue?from=1681159917&to=1683751930",
  "code": 200,
  "result": {
    "from": 1681159917,
    "to": 1683751930,
    "revenue": "398.60636332000007",
    "currency": "EUR",
    "formatted": "398,61€",
    "sales": 21
  }
}

[GET] /users/count

GET /v1/bot{{BOT_ID}}/{{API_KEY}}/users/count

This API method returns the number of known users, leads, churned customers, and paying members.

Response

{
  "ok": true,
  "request_id": "123456789",
  "method": "GET",
  "path": "/users/count",
  "code": 200,
  "result": {
    "users": 6405,
    "leads": 5651,
    "churned": 6,
    "members": 864
  }
}

[DELETE] /webhook

DELETE /v1/bot{{BOT_ID}}/{{API_KEY}}/webhook

This method allows you to remove an existing webhook associated with your Telegram bot. Provide the endpoint URL for the webhook you wish to delete, and the webhook will be removed from your bot.

Request Body

Name Type Description

Name	Type	Description
`url`*	String	The URL of your webhook. It must be a valid URL starting with https://.

url*

String

The URL of your webhook. It must be a valid URL starting with https://.

Response

{
    "ok": true,
    "code": 204
}

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/webhook",
    "code": 400,
    "description": "Bad request: 'url' must match pattern \"^https?://\""
}

Reason: The url provided is invalid.
Solution: Ensure the url starts with "https://".

{
  "ok": true,
  "request_id": "123456789",
  "method": "DELETE",
  "path": "/webhook",
  "code": 404,
  "description": "Not Found: The requested resource could not be found"
}

Reason: You are trying to delete a webhook that doesn't exist in your bot's database.
Solution: N/A

[POST] /webhook

POST /v1/bot{{BOT_ID}}/{{API_KEY}}/webhook

This API method allows you to register a webhook endpoint to receive notifications for events related to your account. Once you have registered a webhook endpoint, we will send HTTP POST requests to that endpoint whenever an event of interest occurs.

Request Body

Name Type Description

Name	Type	Description
`url`*	String, required	The URL of your webhook. It must be a valid URL starting with https:// and responding with HTTP 200 to requests, particularly POST.

url*

String, required

The URL of your webhook. It must be a valid URL starting with https:// and responding with HTTP 200 to requests, particularly POST.

Response

{
    "ok": true,
    "request_id": "123456789",
    "method": "POST",
    "path": "/webhook",
    "code": 201,
    "result": [{
        "url": "https://example.com/",
        "secret": "abcd123"
    }]
}

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/webhook",
    "code": 400,
    "description": "Bad request: 'url' must match pattern \"^https?://\""
}

Reason: The url provided is invalid.
Solution: Ensure the url starts with "https://".

{
    "ok": false,
    "request_id": "123456789",
    "method": "POST",
    "path": "/webhook",
    "code": 409,
    "description": "You have already set a webhook for this bot."
}

Reason: TGmembership only allows one webhook per bot, and you currently have one installed.
Solution: You can delete the current webhook and add a new one.

PreviousAnalytics NextCreate API key

Last updated 6 hours ago