Skip to main content
POST
/
api
/
check-expiry
Check Subscription Expiry
curl --request POST \
  --url https://api.example.com/api/check-expiry \
  --header 'Content-Type: application/json' \
  --data '
{
  "saas_key": "<string>",
  "domain": "<string>"
}
'
{
  "error": "<string>"
}

​
Endpoint

POST /api/check-expiry

​
Authentication

This endpoint requires SaaS Key authentication via the check.expiry middleware.

​
Request Parameters

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

​
Request

curl -X POST "https://your-domain.com/api/check-expiry" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "saas_key": "YOUR_SAAS_KEY",
    "domain": "customer-domain.com"
  }'

​
Response

Returns a plain text response indicating subscription status.

​
Success Response

YES

​
Response Values

ResponseDescription
YESSubscription is active (end_at is in the future)
NOSubscription has expired (end_at is in the past)

​
Error Responses

​
error
string
Error message describing what went wrong
Status CodeDescription
200Success - Returns YES or NO
401Unauthorized - Invalid or missing saas_key

​
How It Works

The endpoint performs the following steps:
1

Validate SaaS Key

Middleware checks if the provided saas_key matches the environment variable SAAS_KEY
2

Trim Domain

The domain parameter is processed through the trimDomain() helper function to normalize it
3

Query Subscription

Looks up the subscription record in the database by domain
4

Compare Dates

Compares the subscription’s end_at date with the current timestamp
5

Return Result

Returns YES if active, NO if expired

​
Notes

  • The domain is automatically normalized using the trimDomain() function
  • Comparison uses Carbon’s now() for accurate timezone handling
  • Response is plain text, not JSON
The saas_key must match the SAAS_KEY environment variable exactly. Keep this key secure and never expose it in client-side code.

​
Example Use Cases

​
Check Before Allowing Access

<?php
function check_subscription_status($domain) {
    $response = wp_remote_post('https://your-domain.com/api/check-expiry', [
        'body' => json_encode([
            'saas_key' => env('SAAS_KEY'),
            'domain' => $domain
        ]),
        'headers' => [
            'Content-Type' => 'application/json',
            'Accept' => 'application/json'
        ]
    ]);
    
    if (is_wp_error($response)) {
        return false;
    }
    
    $result = wp_remote_retrieve_body($response);
    return $result === 'YES';
}

// Usage
if (check_subscription_status('customer-domain.com')) {
    // Allow access to feature
    echo "Welcome! Your subscription is active.";
} else {
    // Deny access
    echo "Your subscription has expired. Please renew.";
}

​
Middleware for Access Control

// Express.js middleware example
async function checkSubscription(req, res, next) {
  const domain = req.user.domain;
  
  try {
    const response = await fetch('https://your-domain.com/api/check-expiry', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        saas_key: process.env.SAAS_KEY,
        domain: domain
      })
    });
    
    const result = await response.text();
    
    if (result === 'YES') {
      next(); // Subscription active, proceed
    } else {
      res.status(403).json({
        error: 'Subscription expired',
        message: 'Please renew your subscription to continue'
      });
    }
  } catch (error) {
    res.status(500).json({ error: 'Failed to verify subscription' });
  }
}

// Use in routes
app.get('/api/protected-resource', checkSubscription, (req, res) => {
  res.json({ data: 'Protected resource' });
});

​
Scheduled Expiry Check

import requests
from datetime import datetime

def check_all_subscriptions(domains):
    """Check expiry status for multiple domains"""
    results = []
    
    for domain in domains:
        response = requests.post(
            'https://your-domain.com/api/check-expiry',
            json={
                'saas_key': 'YOUR_SAAS_KEY',
                'domain': domain
            }
        )
        
        is_active = response.text == 'YES'
        results.append({
            'domain': domain,
            'active': is_active,
            'checked_at': datetime.now().isoformat()
        })
    
    return results

# Usage: Check multiple customer subscriptions
domains = ['customer1.com', 'customer2.com', 'customer3.com']
statuses = check_all_subscriptions(domains)

for status in statuses:
    print(f"{status['domain']}: {'Active' if status['active'] else 'Expired'}")

Usage Limits

Check and manage usage limits

Authentication

Learn about SaaS Key authentication

Build docs developers (and LLMs) love

Get started for freeTalk to us