Skip to main content

​
Endpoint

GET /api/subscriber-status/:tenantSlug
Returns the current billing enforcement status for a subscriber. This is the same endpoint called by the enforcement snippet and all mobile SDKs.

​
Request

​
Path parameters

ParameterDescription
tenantSlugYour SteadPay tenant slug

​
Query parameters

ParameterRequiredDescription
stripe_customer_id✓The subscriber’s Stripe customer ID (cus_…)

​
Headers

HeaderValue
AuthorizationBearer <publishableKey>

​
Example

GET /api/subscriber-status/acme?stripe_customer_id=cus_xxxxxxxxxxxxxxxx
Authorization: Bearer pk_live_abc123

​
Response

{
  "status": "warning",
  "card_update_url": "https://steadpayhq.com/update-card?tenant=acme&token=xxx",
  "entitlements": {
    "powered_by_watermark": true,
    "custom_domain": false,
    "downstream_webhooks": false
  }
}

​
Fields

FieldTypeDescription
status"active" | "warning" | "lockout"Current billing enforcement status
card_update_urlstring | nullURL to the card update page. Present when status is "warning" and a card update URL is configured
entitlementsobjectCapability flags for the subscriber’s tenant tier

​
Status values

StatusMeaning
activePayment is current — no enforcement shown
warningSoft decline — show dismissable banner nudging card update
lockoutHard decline or exhausted retries — show full-screen gate

​
Error responses

StatusMeaning
401 UnauthorizedMissing or invalid publishable key
402 Payment RequiredTenant’s SteadPay subscription is suspended
404 Not FoundTenant slug not found

​
Unknown subscribers

If SteadPay has not seen a given stripe_customer_id before (no failed payment on record), the response is: 
{ "status": "active" }
SteadPay is fail-open — an unknown subscriber is treated as active so your app never blocks users due to missing data.