Skip to main content

​
Overview

These API endpoints provide access to subscription information including user data, expiration status, payment history, and access restrictions.

​
Authentication

All subscription data endpoints use the check.expiry middleware which requires a valid saas_key parameter.
See Authentication for details on SaaS Key authentication.

​
Get User Subscription Data

Retrieve complete subscription details for a user. 
GET /api/user-subscription-data

​
Request Parameters

​
saas_key
string
required
SaaS authentication key matching the environment variable SAAS_KEY
​
domain
string
required
Customer domain to retrieve subscription data for

​
Response

​
user_id
integer
Unique identifier for the user
​
subscription_id
integer
Current subscription ID
​
package_id
integer
Subscribed package identifier
​
package_name
string
Name of the subscription package
​
status
string
Subscription status (active, expired, suspended)
​
start_date
string
Subscription start date (ISO 8601 format)
​
end_date
string
Subscription expiration date (ISO 8601 format)
​
email_limit
integer
Total email credits available
​
sms_limit
integer
Total SMS credits available
​
call_credits
number
Remaining call credits in currency

​
Example Request

curl -X GET "https://your-domain.com/api/user-subscription-data?saas_key=YOUR_SAAS_KEY&domain=customer.com" \
  -H "Accept: application/json"

​
Get Subscription Expiration Date

Calculate days remaining until subscription expiration. 
GET /api/user-subscription-date-endin

​
Request Parameters

​
saas_key
string
required
SaaS authentication key
​
domain
string
required
Customer domain

​
Response

​
days_remaining
integer
Number of days until subscription expires
​
expiration_date
string
Subscription end date (ISO 8601 format)
​
is_expired
boolean
Whether the subscription has already expired

​
Example Request

curl -X GET "https://your-domain.com/api/user-subscription-date-endin?saas_key=YOUR_SAAS_KEY&domain=customer.com" \
  -H "Accept: application/json"

​
Get Payment History

Retrieve payment transaction history for a user. 
GET /api/payment-histories

​
Request Parameters

​
saas_key
string
required
SaaS authentication key
​
domain
string
required
Customer domain
​
limit
integer
Number of records to return (default: 10, max: 100)
​
offset
integer
Pagination offset (default: 0)

​
Response

Returns an array of payment history objects:
​
id
integer
Payment record ID
​
user_id
integer
User who made the payment
​
package_id
integer
Package purchased
​
amount
number
Payment amount
​
currency
string
Payment currency code (USD, EUR, etc.)
​
payment_method
string
Gateway used (stripe, paypal, razorpay, etc.)
​
transaction_id
string
Gateway transaction identifier
​
status
string
Payment status (completed, pending, failed)
​
created_at
string
Payment timestamp (ISO 8601 format)

​
Example Request

curl -X GET "https://your-domain.com/api/payment-histories?saas_key=YOUR_SAAS_KEY&domain=customer.com&limit=20" \
  -H "Accept: application/json"

​
Check User Restrictions

Verify if a user has any access restrictions due to subscription status. 
GET /api/user-restriction

​
Request Parameters

​
saas_key
string
required
SaaS authentication key
​
domain
string
required
Customer domain

​
Response

​
restricted
boolean
Whether the user has restrictions
​
reason
string
Restriction reason (expired, suspended, payment_failed, etc.)
​
message
string
Human-readable restriction message
​
restricted_features
array
List of features the user cannot access

​
Example Request

curl -X GET "https://your-domain.com/api/user-restriction?saas_key=YOUR_SAAS_KEY&domain=customer.com" \
  -H "Accept: application/json"

​
Error Responses

All endpoints return standard error responses:
​
error
string
Error message
​
code
string
Error code (INVALID_SAAS_KEY, USER_NOT_FOUND, etc.)

​
Common Error Codes

CodeDescription
INVALID_SAAS_KEYThe provided SaaS key is invalid
USER_NOT_FOUNDNo user found for the specified domain
SUBSCRIPTION_NOT_FOUNDUser has no active subscription
INVALID_DOMAINDomain format is invalid

​
Usage Example

Here’s a complete workflow for checking subscription status: 
async function checkSubscriptionStatus(domain) {
  const saasKey = 'YOUR_SAAS_KEY';
  const baseUrl = 'https://your-domain.com/api';
  
  // 1. Check if subscription has expired
  const expiryResponse = await fetch(
    `${baseUrl}/check-expiry?saas_key=${saasKey}&domain=${domain}`
  );
  const expiry = await expiryResponse.json();
  
  if (expiry.expired === 'YES') {
    console.log('Subscription expired');
    return;
  }
  
  // 2. Get subscription details
  const dataResponse = await fetch(
    `${baseUrl}/user-subscription-data?saas_key=${saasKey}&domain=${domain}`
  );
  const subscription = await dataResponse.json();
  
  console.log(`Package: ${subscription.package_name}`);
  console.log(`Email credits: ${subscription.email_limit}`);
  console.log(`SMS credits: ${subscription.sms_limit}`);
  
  // 3. Check for restrictions
  const restrictionResponse = await fetch(
    `${baseUrl}/user-restriction?saas_key=${saasKey}&domain=${domain}`
  );
  const restriction = await restrictionResponse.json();
  
  if (restriction.restricted) {
    console.log(`Access restricted: ${restriction.reason}`);
  }
}

​
Next Steps

Usage Limits

Check and manage email/SMS usage

Check Expiry

Verify subscription expiration

Subscription Packages

Learn about available packages

Payment Gateways

Configure payment methods

Build docs developers (and LLMs) love

Get started for freeTalk to us