Checking access

GET /api/v1/access

Parameter
ref	Your id for the user, as passed to the subscribe page. Use this or email
email	The subscriber's email, when you don't use refs
product_id	Only look at one product's subscriptions. Leave it out to accept any of your plans

curl "https://paylead.app/api/v1/access?ref=USER_123" \
  -H "Authorization: Bearer sk_live_your_key"

The answer

{
  "has_access": true,
  "status": "past_due",
  "access_ends_at": "2026-11-13T09:00:00+00:00",
  "subscription": {
    "id": "sub_8f2k1m0q9z",
    "object": "subscription",
    "status": "past_due",
    "has_access": true,
    "ref": "USER_123",
    "product": { "id": 31, "name": "Pro plan" },
    "amount": 50,
    "currency": "GHS",
    "interval": "month",
    "current_period_end": "2026-11-10T09:00:00+00:00",
    "access_ends_at": "2026-11-13T09:00:00+00:00",
    "manage_url": "https://paylead.app/subscription/…"
  }
}

Field
has_access	true if any of the user's subscriptions is paid up or in its grace period
status	The status of the subscription shown, or null if they never subscribed
access_ends_at	When access stops if they don't renew
subscription	The subscription giving access, or their latest one, or null

Someone who never subscribed gets has_access: false and subscription: null, not an error.

If a user has several subscriptions (for example to two plans), has_access is true when any of them gives access, and subscription is the one that lasts longest.

Tips

• Show a renew banner when status is past_due: link it to subscription.manage_url.
• Cache it. Access only changes when someone pays, a period ends or they cancel. Checking on sign-in, or caching for a few minutes, is plenty. You can make 120 requests a minute per key.
• Or skip polling and keep your own copy up to date with webhooks.