Billing

Read effective plan limits and live usage for the API key account. Read-only: checkout, portal, and Stripe session creation are not available on public REST.

Base path: /api/v1/billing. Scope: billing: read. See Authentication and Scopes.

For the raw subscription row (Stripe customer id, status, period end), use Subscriptions (subscriptions: read).

Concepts

• Entitlements: resolved limits and feature flags for the current plan, plus one-time unlock flags (lifetime custom fields, donor supporter).
• Plan usage: entitlements plus live usage counts for billing meters in settings UI.

Plan keys: free, pro, pro_plus. Unlimited numeric limits serialize as null in JSON when represented as Infinity in TypeScript.

Endpoint index

Both routes reject query parameters with 400.

Get entitlements

GET/api/v1/billing/entitlements

Returns Entitlements for the API key user: planKey, limits, features, lifetimeCustomFieldsUnlocked, donorSupporterUnlocked.

{
  "planKey": "pro",
  "limits": {
    "templates": null,
    "fileUploadBytes": 52428800,
    "customFieldsPerMember": null,
    "notesPerMember": null,
    "customColorSchemes": 5,
    "uploadedCustomIcons": 20,
    "uploadedCustomFonts": 5
  },
  "features": {
    "canUseGifAvatar": true,
    "canUseCustomColors": true,
    "canUseCustomIcons": true,
    "canUseAnimatedIcons": false,
    "canUseCustomFonts": true
  },
  "lifetimeCustomFieldsUnlocked": false,
  "donorSupporterUnlocked": true
}

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/billing/entitlements"

Get plan usage

GET/api/v1/billing/plan-usage

PlanUsageSnapshot: entitlements plus usage counts. Per-member caps use the maximum on any single member (maxNotesPerMember, maxCustomFieldsPerMember).

{
  "planKey": "pro",
  "limits": { "...": "same shape as entitlements.limits" },
  "features": { "...": "same shape as entitlements.features" },
  "fileUploadMaxBytes": 52428800,
  "templates": null,
  "customIcons": 5,
  "customFonts": 1,
  "customColorSchemes": 2,
  "maxNotesPerMember": 12,
  "maxCustomFieldsPerMember": 4
}

curl -sS \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://api.floralitys.com/api/v1/billing/plan-usage"

Errors

JSON { "code", "message" }:

• UNAUTHORIZED (401): invalid or missing API key
• FORBIDDEN (403): missing billing: read
• BAD_REQUEST (400): unknown query parameters
• PRECONDITION_FAILED (503): DATABASE_URL not configured

See Errors.

{
  "code": "PRECONDITION_FAILED",
  "message": "PostgreSQL is not configured (DATABASE_URL)."
}