api.botsubscription.com

GET/v1/endpoint

AuthenticationBearer

Token

Stays in this tab. Required for this endpoint — the value below is what gets sent.

Path parameters0

Query parameters0

Headers0

BodyJSON

Examples

curl --request GET \
  --url https://api.botsubscription.com/v1/endpoint \
  --header 'Authorization: Bearer sk_live_•••'

List Memberships - View Active Subscriptions in Your Bot

Get all active and past subscriptions across your project. Each membership record shows which user holds it, the plan they purchased, subscription dates, and renewal status. You can filter by user ID to view a specific member's subscription history.

membership_end_date may be null for memberships with no scheduled end date. The subscription_id and subscription_status fields are populated only for recurring memberships and may otherwise be null or omitted.

GET/v2/projects/{project_id}/memberships

Authorization

Bearer API KeyRequired

API key scope: memberships:read (required for restricted keys).

Path Parameters

project_idstringrequired

The unique identifier of the project.

Query Parameters

user_idstring

Filter memberships to a single user.

allboolean

Request every membership in the project. Project API keys already return all memberships by default.

limitintegerDefault: 10

Number of items per page (1–100).

offsetintegerDefault: 0

Number of items to skip.

curl -X GET "https://api.botsubscription.com/v2/projects/YOUR_PROJECT_ID/memberships?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

const project_id = 'YOUR_PROJECT_ID';
const response = await fetch(`https://api.botsubscription.com/v2/projects/${project_id}/memberships?limit=20`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});
const data = await response.json();

import requests
 
project_id = 'YOUR_PROJECT_ID'
response = requests.get(
    f'https://api.botsubscription.com/v2/projects/{project_id}/memberships',
    params={'limit': 20},
    headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
data = response.json()

$project_id = 'YOUR_PROJECT_ID';
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.botsubscription.com/v2/projects/{$project_id}/memberships?limit=20");
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer YOUR_API_KEY']);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);

Successapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/memberships",
  "code": 200,
  "total": 1,
  "message": "All memberships retrieved successfully",
  "data": [
    {
      "user_id": "123456789012345678",
      "plan_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "membership_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "payment_request_id": "cccccccc-cccc-cccc-cccc-cccccccccccc",
      "membership_start_date": "2025-12-29T10:32:27.560Z",
      "membership_end_date": "2026-01-12T10:32:27.560Z",
      "user_name": {
        "first_name": "John",
        "username": "johndoe"
      },
      "plan_name": "Silver",
      "plan_duration": "1 day",
      "subscription_id": null,
      "subscription_status": null,
      "access_token_id": null
    }
  ]
}

Membership without a finite end dateapplication/json

{
  "ok": true,
  "request_id": "11111111-1111-1111-1111-111111111111",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/memberships",
  "code": 200,
  "total": 1,
  "message": "All memberships retrieved successfully",
  "data": [
    {
      "user_id": "123456789012345678",
      "plan_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
      "membership_id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
      "membership_start_date": "2025-12-29T10:32:27.560Z",
      "payment_request_id": null,
      "membership_end_date": null
    }
  ]
}

Invalid page limitapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/memberships",
  "code": 422,
  "errors": [
    {
      "message": "query: limit is too small; minimum allowed is 1",
      "error_code": "VALIDATION_ERROR"
    }
  ]
}

Invalid or expired API keyapplication/json

{
  "ok": false,
  "request_id": "44444444-4444-4444-8444-444444444444",
  "method": "GET",
  "path": "/v2/projects/11111111-1111-4111-8111-111111111111/memberships",
  "code": 401,
  "error": {
    "message": "Invalid or expired authentication token.",
    "error_code": "UNAUTHORIZED"
  }
}

Last updated: November 4, 2026