Entitlements API

The entitlements API lets a merchant's own systems — a Discord bot, a gated content site, an internal tool — check whether a customer is currently entitled, in one call. It is read-only, and the first endpoint of the WallaB Developer Platform, an AI-ready data API.

#Plan requirement

The WallaB Developer Platform is available on the Growth plan and above. On Free or Starter, key creation is locked and requests are refused with:

{ "success": false, "message": "Developer API access requires the Growth plan or higher." }

#Authentication

Create an API key in Settings → WallaB Developer Platform (owner-only). Keys look like wlb_ followed by 43 URL-safe characters, are shown exactly once at creation (only a hash is stored), and can be revoked at any time — a revoked key fails immediately.

Send the key as a bearer token:

Authorization: Bearer wlb_your_key_here

Any missing, malformed, unknown, or revoked key gets the identical generic response — 401 {"success": false, "message": "Unauthorized"} — the API never reveals which check failed.

#Scopes

Each key carries read-only scopes; grant only what a key needs:

• read:entitlements — customer entitlement status (this endpoint).
• read:subscriptions — subscription records and status.
• read:metrics — aggregate retention and revenue metrics.
• read:plans — selling-plan definitions.

A key that lacks the scope an endpoint requires is refused with 403. Only read:entitlements is wired to an endpoint today; the others are reserved for upcoming endpoints so keys never need re-issuing.

#The endpoint

GET /api/external/v1/entitlements?customerId=123

The unversioned /api/external/entitlements path is kept as a permanent alias for existing integrations; new integrations should use the /v1 path.

customerId is WallaB.AI™'s internal numeric customer id (a positive integer). It is deliberately not an email: the id is opaque and scoped to your shop, while an email in a query string would ride through access logs as plaintext PII.

#Response

{
  "subscriptions": [
    {
      "subscriptionId": 42,
      "planId": 7,
      "planName": "Coffee Club Monthly",
      "planType": "physical",
      "status": "active",
      "isEntitled": true
    }
  ]
}

One entry per subscription the customer has in your shop. A customer id that doesn't exist, has no subscriptions, or belongs to a different shop returns an empty array — never a 404 — so the endpoint can't be used to probe which ids exist.

#Errors

• 400 — customerId missing or not a positive integer.
• 401 — any authentication failure (uniform body, see above).
• 403 — the plan lacks API access, or the key lacks the required scope.
• 429 — rate limited; the Retry-After header says how long to wait.
• 500 — something went wrong on our side; safe to retry later.

#Rate limits

Requests are limited per API key, by plan: Growth = 60 requests per minute, Pro = 300 requests per minute, and Enterprise Plus = unlimited. Exceeding it returns 429 with a Retry-After header (seconds). Design your integration to cache entitlement results briefly rather than checking on every page view.