Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.manticscore.com/llms.txt

Use this file to discover all available pages before exploring further.

The billing endpoints expose the current user’s credit balance and subscription state, and accept lifecycle events from RevenueCat. iOS reads GET /v1/usage on every app launch and after every paywall presentation — it is the single source of truth for “what does this user have access to right now”.

​
Get current usage

Returns the current monthly billing period, the user’s tier with caps, current consumption, and remaining allowance. Rate limit: 120 requests per minute. 
curl https://api.manticscore.com/v1/usage \
  -H "Authorization: Bearer <session_token>"
200 response
{
  "period": {
    "key": "2026-05",
    "resets_at": "2026-06-01T00:00:00+00:00"
  },
  "tier": {
    "id": "free",
    "product_id": null,
    "caps": {
      "questions": 50,
      "tts_minutes": 5.0,
      "credits": 20
    }
  },
  "used": {
    "questions": 0,
    "tts_seconds": 0.0,
    "credits": 6
  },
  "remaining": {
    "questions": 50,
    "tts_minutes": 5.0,
    "credits": 14
  }
}
​
period
object
required
​
tier
object
required
​
used
object
required
​
remaining
object
required

​
Tier caps reference

TierQuestionsTTS minutesCredits
free50520
explorer50060200
plus1500180300
pro2500300400
early_access10000010000100000
New users with no profile row receive a default response: tier.id: "free", the free-tier caps, and zeroed counters. The profile row is created lazily on first call to GET /profile.
The previous /v1/usage shape (plan, credits.{used,total,remaining,resets_at,weights}, subscription.{...}) has been replaced. Subscription lifecycle data now lives on GET /profile and individual webhook events; tier identity and entitlement are derived from tier.id here. Per-action credit weights are documented under Credits.

​
RevenueCat webhook

Endpoint that RevenueCat calls to deliver subscription lifecycle events. You do not call this endpoint directly — configure it once in the RevenueCat dashboard under Project → Integrations → Webhook. 
POST /api/v1/billing/rc-webhook
Rate limit: 600 requests per minute.

​
Authentication

Two layers, both required when configured:
  1. Bearer token (required). The value of the Authorization header is compared in constant time to the secret configured in the RevenueCat dashboard. 
    Authorization: Bearer <revenuecat_webhook_secret>
  2. HMAC-SHA256 body signature (optional, defense-in-depth). When revenuecat_signing_secret is configured server-side, requests must include a hex digest of the raw body in the X-RevenueCat-Signature header. The verification path is currently dormant because RevenueCat removed the signing-secret field from current dashboards; leave the secret unset to skip this check.
If the bearer is invalid the endpoint returns 401. If the JSON body is malformed it returns 400. All other outcomes — including event-handler exceptions — return 200 so RevenueCat does not enter retry backoff for issues that require a code fix. The event row is always written to the audit table first, so failed events can be replayed from there.

​
Handled event types

RevenueCat eventSubscription status
INITIAL_PURCHASEactive
RENEWALactive
NON_RENEWING_PURCHASEactive
UNCANCELLATIONactive
PRODUCT_CHANGEactive
CANCELLATIONactive (auto-renew off; entitled until expiry)
EXPIRATIONexpired
BILLING_ISSUEin_billing_retry
SUBSCRIPTION_PAUSEDpaused
SUBSCRIBER_ALIASaudit-only
TRANSFERaudit-only
TESTaudit-only
After processing the event, the server fetches the canonical subscription list from GET /v2/projects/{project_id}/customers/{customer_id}/subscriptions and reconciles the user’s stored state against RevenueCat’s authoritative view. Reconciliation is best-effort — a transient failure does not fail the webhook. Each successful entitlement state flip also fires a usage.changed silent control envelope over the realtime gateway so the user’s iOS client refreshes /v1/usage immediately without waiting for the next foreground poll.
200 response (test event)
{
  "ok": true,
  "audit_only": true,
  "type": "TEST"
}
200 response (deferred after handler exception)
{
  "ok": true,
  "deferred": true,
  "reason": "internal_error"
}
Every webhook event is appended to an audit table before any state mutation. If the handler is updated later, historical events can be re-processed from the audit trail without asking RevenueCat to replay.