Subscriber Status

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

Parameter	Description
`tenantSlug`	Your Gatlio tenant slug

Query parameters

Parameter	Required	Description
`stripe_customer_id`	✓	The subscriber’s Stripe customer ID (`cus_…`)
`hmac`		`HMAC-SHA256(hmacSecret, stripe_customer_id)`. Strongly recommended in production — prevents a client from spoofing another subscriber’s customer ID

Headers

Header	Value
`Authorization`	`Bearer <publishableKey>`

Example

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

Response

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

Fields

Field	Type	Description
`status`	`"active" \| "warning" \| "lockout"`	Current billing enforcement status
`card_update_url`	`string \| null`	URL to the card update page. Present when `status` is `"warning"` and a card update URL is configured
`entitlements`	`object`	Capability flags for the subscriber’s tenant tier

Status values

Status	Meaning
`active`	Payment is current — no enforcement shown
`warning`	Soft decline — show dismissable banner nudging card update
`lockout`	Hard decline or exhausted retries — show full-screen gate

Error responses

Status	Meaning
`401 Unauthorized`	Missing or invalid publishable key
`402 Payment Required`	Tenant’s Gatlio subscription is suspended
`404 Not Found`	Tenant slug not found

Unknown subscribers

If Gatlio has not seen a given stripe_customer_id before (no failed payment on record), the response is:

{ "status": "active" }

Gatlio is fail-open — an unknown subscriber is treated as active so your app never blocks users due to missing data.

Get Started

Enforcement Snippet

Mobile SDKs

API Reference

Webhooks

Dashboard

Subscriber Status

Endpoint

Request

Path parameters

Query parameters

Headers

Example

Response

Fields

Status values

Error responses

Unknown subscribers

​Endpoint

​Request

​Path parameters

​Query parameters

​Headers

​Example

​Response

​Fields

​Status values

​Error responses

​Unknown subscribers

Endpoint

Request

Path parameters

Query parameters

Headers

Example

Response

Fields

Status values

Error responses

Unknown subscribers