Partner-Managed Billing & ClearTrust Integration

These docs let any platform (your “tenant”) control a user’s ClearTrust tier and add-ons from your own billing/subscription logic. ClearTrust will not charge your users directly when Partner-Managed Billing is enabled.

You’ll Use:

API Keys you create in Developer & API Setup → API Keys

(Optional) Webhooks you configure in Developer & API Setup → Webhooks

1) Concepts

Tenant: your white-label platform inside RegimeOS.
Partner-Managed Billing: when enabled for your tenant, in-app Stripe UI is hidden; you set tiers by API.
ClearTrust Tier: basic, pro, or elite.
Add-ons: currently visibility_boost (boolean).
PartnerPlanMap: your mapping of your plans → ClearTrust tiers & modules.

2) Authentication

All Partner APIs require:

POST requests
Header: Content-Type: application/json
Header: api_key: <YOUR_TENANT_API_KEY>

Create API keys in Developer & API Setup → API Keys.

3) Endpoints

Base URL pattern:

https://app.base44.com/api/apps/<REGIMEOS_APP_ID>/functions/partner/

3.1 Upsert User Tier

Assign or update a user’s ClearTrust tier and add-ons.

Endpoint

POST /functions/partner/upsertUserTier

Body

{
  "external_user_id": "usr_12345",
  "email": "pro@yourplatform.com",
  "plan": "Growth",
  "visibility_boost": true,
  "effective_at": "2025-08-29T12:00:00Z"
}

Response

{
  "ok": true,
  "user_id": "68ab…",
  "tier": "pro",
  "addons": { "visibility_boost": true }
}

Notes

We match users by external_user_id or email. If not found, the user is created.
plan is mapped via your PartnerPlanMap (see §4).

3.2 Revoke User Access

Deactivate ClearTrust modules for a user.

Endpoint

POST /functions/partner/revokeUserAccess

Body (one of external_user_id or email is required)

{ "external_user_id": "usr_12345", "reason": "plan_downgrade" }

Response

{ "ok": true, "user_id": "68ab…", "status": "revoked" }

3.3 Sync User Profile (Optional)

Send profile metadata so ClearTrust/CRM/AI can personalize.

Endpoint

POST /functions/partner/syncUserProfile

Body

{
  "external_user_id": "usr_12345",
  "profile": {
    "company": "Acme Jewelers",
    "phone": "+1-555-123-4567",
    "website": "https://acme.example",
    "socials": { "instagram": "acmejewelers" },
    "location": { "city": "Austin", "state": "TX", "country": "US" }
  }
}

Response

{ "ok": true }

4) PartnerPlanMap (Your Plan → ClearTrust)

Define how your plans map to ClearTrust. You can manage this via the Admin UI (Developer & API Setup) or request support to seed it.

Example Mapping

| Partner Plan | ClearTrust Tier | Modules Enabled | visibility_boost | |--------------|-----------------|---------------------------------------------|------------------| | Starter | basic | cleartrust.core | false | | Growth | pro | cleartrust.core, cleartrust.analytics | optional | | Elite | elite | cleartrust.core, cleartrust.analytics, cleartrust.ai_review | optional |

The result controls:

subscription_tier on the user
subscribed_modules your users can access
active_addons.visibility_boost when set

5) Example Requests

cURL – Upsert Tier

curl -X POST "https://app.base44.com/api/apps/<REGIMEOS_APP_ID>/functions/partner/upsertUserTier" \
  -H "Content-Type: application/json" \
  -H "api_key: <YOUR_TENANT_API_KEY>" \
  -d '{
    "external_user_id": "usr_12345",
    "email": "pro@yourplatform.com",
    "plan": "Growth",
    "visibility_boost": true
  }'

JavaScript – Upsert Tier (server-side)

await fetch("https://app.base44.com/api/apps/<REGIMEOS_APP_ID>/functions/partner/upsertUserTier", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api_key": process.env.REGIMEOS_API_KEY
  },
  body: JSON.stringify({
    external_user_id: "usr_12345",
    email: "pro@yourplatform.com",
    plan: "Growth",
    visibility_boost: true
  })
});

6) Webhooks (Optional)

Set a webhook URL in Developer & API Setup → Webhooks. Choose events you want to receive:

user.tier_changed
user.addons_changed
trust.score_updated
trust.profile_updated

Security

We sign payloads with HMAC SHA-256 using your webhook secret.
Verify signature per the Webhook Guide.

Sample Payload

{
  "id": "evt_01JABC123",
  "type": "user.tier_changed",
  "occurred_at": "2025-08-29T18:10:04Z",
  "tenant_id": "ten_abc123",
  "data": {
    "user_id": "usr_68ab...",
    "external_user_id": "usr_12345",
    "previous": { "tier": "basic", "addons": { "visibility_boost": false } },
    "current":  { "tier": "pro",   "addons": { "visibility_boost": true  } }
  }
}

7) Hiding Stripe UI (Partner-Managed Billing)

When your tenant’s Partner-Managed Billing flag is enabled:

End-user billing/upgrade screens in ClearTrust will show: “Your subscription level is managed by your platform administrator.”
All in-app Stripe flows are disabled. You control tiers via API.

To enable this, contact support or your RegimeOS admin.

8) Recommended Flow

User buys/changes plan on your platform.
Your backend calls upsertUserTier with your plan (we map it to ClearTrust).
(Optional) Call syncUserProfile.
We emit webhooks (if configured).
The user’s ClearTrust experience updates immediately.

9) Troubleshooting

401 Unauthorized: Missing/invalid api_key.
405 Method Not Allowed: Must use POST.
Mapping issues: Ensure your plan exists in PartnerPlanMap.
No UI change: Confirm Partner-Managed Billing is enabled for your tenant.

10) Support

Use the Partner Integration Diagnostics tool to test keys, requests, and webhooks.
Open a ticket with your request ID, sample payloads, and timestamps for fastest help.