Tenant API

Add-on usage breakdown (PlatformAdmin only).

List billing events for a tenant (PlatformAdmin only).

Churn metrics over a given number of months (PlatformAdmin only).

Get a single tenant by ID (PlatformAdmin only).

List all active country exclusivity agreements. PlatformAdmin only.

List every configured channel. PlatformAdmin only.

List all active region (city) exclusivity agreements. PlatformAdmin only.

List tenant registrations with optional status filter (PlatformAdmin only).

List tenants with optional search and status filter (PlatformAdmin only).

Enumerate every event kind the platform can fire — the UI uses this to populate the subscription checkbox list so new events appear automatically after a migration.

Overall platform usage metrics (PlatformAdmin only).

Platform-wide revenue metrics (PlatformAdmin only).

List all subscriptions (PlatformAdmin only).

Subscription breakdown by plan (PlatformAdmin only).

Subscription breakdown by status (PlatformAdmin only).

Operational activity snapshot for a specific tenant (PlatformAdmin only). Returns total account counts broken down by role, total order counts broken down by kind and lifecycle status, and a 30-day daily series of new accounts + orders so the admin console can visualize how an individual tenant is tracking through its setup.

Get the current branding configuration for a specific tenant (PlatformAdmin only).

Get onboarding status for any tenant (PlatformAdmin only).

List the *active* operation cities for a tenant (PlatformAdmin only). Backward-compatible shape: returns only ACTIVE rows so existing admin console clients reading this field keep working. Use adminTenantOperationCityList when the admin needs to see paused (DISABLED_BY_PLAN / DISABLED_BY_TENANT) rows too.

Full operation-city allow-list for a tenant — active and disabled rows — for the platform-admin tenant detail UI (PlatformAdmin only). Mirrors the tenant-side myOperationCityList so support staff see the same picture the tenant sees, including cities that were auto-shrunk on a plan downgrade.

Admin view of any tenant's platform addons. Includes audit fields (granted_by, granted_at, note) and revoked-but-retained rows (enabled = false). PlatformAdmin only.

Quick dashboard aggregation of tenant and registration counts (PlatformAdmin only).

Get a specific tenant's subscription (PlatformAdmin only).

Read any tenant's plan-credit wallet (PlatformAdmin only).

Recent ledger entries for a tenant wallet, newest first (PlatformAdmin only). Capped at limit (default 50, max 200).

Top tenants by transaction volume (PlatformAdmin only).

Trial-to-paid conversion metrics (PlatformAdmin only).

Distribution of tenants across verticals (PlatformAdmin only).

Get the audit log for API key events. Can filter by specific API key ID or get all events for the tenant. Requires TenantAdmin role.

List all API keys for the current tenant. By default, only active (non-revoked) keys are returned. Set includeRevoked to true to include revoked keys. Requires TenantAdmin role.

Browse available plans (public, no auth required).

Get the current branding configuration. Returns the active branding for the current tenant.

Get all branding configuration revisions. Returns the history of branding changes for this tenant.

Get branding configuration by version. Useful for previewing or rolling back to a previous version.

List all cities in a country (for admin dropdowns).

One-shot tenant bootstrap. Returns the tenant identity + every client-facing config slice in a single round-trip. Read by the client SDK at app startup; per-domain queries (branding, mapProviderConfig, …) stay available for admin tools.

Get all country exclusivity tier definitions with pricing.

The tenant's auto-provisioned store-review account. Returns null if the reviewer hasn't been provisioned yet — the frontend should surface a "Provision" CTA in that case.

Discover a tenant by its join code (public, no auth required). The code is case-insensitive. Returns null if no active tenant matches.

Discover a tenant by its domain (public, no auth required). Resolves the tenant from a custom or system domain string (e.g., "acme-rides.bettersuite.io" or "ride.acmetaxi.com"). Returns null if no active tenant matches the domain.

Discover active tenants operating in a specific city (public, no auth required).

Discover active tenants operating in a country (public, no auth required). Returns tenants that have at least one operation city in the given country.

Discover tenants near a geographic location (public, no auth required). Searches via operation cities within the given radius, ordered by distance to the nearest city.

Get exclusivity pricing for specific cities. Returns per-city pricing based on population, along with availability (whether the city is already locked by another tenant). Call this after the tenant has selected their operation cities.

Get exclusivity pricing for specific countries.

Get all exclusivity tier definitions with pricing. Useful for displaying a pricing table in the UI.

Check if a slug is available

Get the current map provider configuration. Returns the active map provider settings for the current tenant, including configured providers (Google Maps, Mapbox, etc.) and their services.

Get the current tenant (based on JWT token)

Returns the platform-controlled addons granted to the caller's tenant. Tenants use this to drive UI gates (showing the "Star members" tab only when the StarTier addon is effective, etc.).

Count of currently-active cities for the tenant. Useful for UI gauges next to the plan's locations limit without round-tripping the full list.

Get the current tenant's active add-ons.

List the current tenant's active country exclusivities.

List all domains (system + custom) for the current tenant.

Get the current tenant's invoice history (upcoming and past).

List the *active* cities assigned to the current tenant. Backward-compatible shape: returns only ACTIVE rows so existing clients reading this field continue to see what they did before. Use myOperationCityList for the full allow-list including disabled rows.

Full allow-list: active and disabled rows. Disabled rows stay in the list with their status/disabledReason so the UI can show reactivate affordances without rediscovering cities.

Aggregated footprint of where the tenant operates: distinct countries, admin regions, and cities, joined with the shared geo reference tables. One round trip for cascading dropdowns (tax zone editor, region setup, dashboard summaries) so each surface doesn't re-derive the dedupe / join logic.

List the current tenant's active region exclusivities.

Get the current tenant's active subscription.

Get the current tenant's usage meters. Event-counter meters (e.g. monthly_transactions) come from the usage-meter store, written by record_usage. State counters (verticals, locations) are synthesized here from their authoritative sources — the active subscription and the operation-area repo — so they can't drift from reality.

Get the current notification settings configuration. Returns the active notification settings for the current tenant.

Get the current parking configuration. Returns the active parking config for the current tenant.

Get the current payment gateway configuration. Returns the active payment gateway config for the current tenant.

Get available add-ons for a plan (public).

Get details for a specific plan (public).

All platform-owned connected apps (shared by every tenant). Callable by tenant admins too — they need to see what they're inheriting (and opt out of) on the domain-admin UI.

Get the current regional settings configuration. Returns locale, measurement system, time format, map defaults, wallet top-up presets, and support contact for the current tenant.

Search reference cities by name prefix (for admin UI dropdowns).

Get the current service configuration. Returns the active service config for the current tenant.

Get the current shop settings configuration. Returns the active shop settings for the current tenant.

Get a tenant by ID (admin operation)

Resolve the tenant's effective AuthPolicy. Never returns null — falls back to the platform default when the tenant has no revision stored.

Connected apps owned by a tenant. Tenant admins omit tenantId (defaults to their own); platform admins may pass any tenantId.

IDs of platform apps the tenant has opted out of. Tenant admins omit tenantId; platform admins may pass any tenantId.

Get public tenant information. Returns tenant info including branding, current plan details, available upgrades, and add-ons. Accessible to all authenticated users within the tenant.

Get the onboarding completion status for the current tenant.

Get all tenants (admin operation)

Get the public tier policy for the current tenant. Apps read this unauthenticated to decide whether to allow guest order creation or pop the registration sheet.

Return the current tenant's plan-credit wallet balance for the given currency. Returns a wallet with exists=false (and zero balances) when the tenant has never been credited — callers should still treat this as a valid empty wallet rather than an error.

Add an addon to the current subscription.

Add a custom domain for a tenant app. The domain must be globally unique. After adding, the tenant must set up a CNAME record pointing to the system subdomain (returned in the entity's cname_target field) and then call verifyCustomDomain.

Add a city to the current tenant's operation areas. If the city is already in the allow-list (any status), the row is reactivated rather than re-inserted. Reactivation and net-new adds both consume one slot of the plan's locations limit.

Re-activate a suspended or cancelled tenant (PlatformAdmin only). Blocked tenants cannot be activated — use adminUnblockTenant instead.

Add a city to a tenant's operation areas (PlatformAdmin only).

Force-assign a plan to a tenant (PlatformAdmin only, bypasses Stripe).

Block a tenant immediately (PlatformAdmin only). Blocked tenants cannot be auto-reactivated by billing events. Use adminUnblockTenant to restore access.

Cancel a pending registration (PlatformAdmin only).

Create a country exclusivity agreement for a tenant. PlatformAdmin only. If monthly_price_minor is omitted the price is auto-calculated from the country's GDP-based value tier.

Create a new notification channel. PlatformAdmin only.

Create a region exclusivity agreement for a tenant. PlatformAdmin only. If monthly_price_minor is omitted the price is auto-calculated from the city's population tier and country GDP data.

Create a new tenant as PlatformAdmin. When skip_verification is true, tenant + admin account are created immediately. When false, an invitation email is sent with a 7-day verification link.

Grant credit to a tenant's plan-credit wallet (PlatformAdmin only). Records an AdminGiftCredit ledger transaction; idempotency is on the caller — every call adds another grant.

Delete a channel. PlatformAdmin only. Returns true on success.

Soft-delete a tenant (PlatformAdmin only). Step-up gated — the platform admin must re-enter their password to mint an elevation token before this mutation will proceed. Tenant deletion is irreversible from the tenant's side, so a stolen platform-admin session cannot wipe a tenant without the password too.

Extend a subscription's period (PlatformAdmin only).

Grant a platform-controlled addon to a tenant. PlatformAdmin only. expires_at = None makes the grant indefinite. Re-granting an existing addon overwrites the previous record (new granted_by and granted_at stamps; new expiry).

Force-create a tenant from a pending or email-verified registration. Admin picks a plan — the tenant, account, and subscription are created immediately, bypassing the user's onboarding flow. PlatformAdmin only. Force-create with a specific plan. Falls back to the registration's plan or the default trial.

Reactivate a cancelled (or cancel-at-period-end) subscription (PlatformAdmin only).

Remove a city from a tenant's operation areas (PlatformAdmin only).

Revoke (deactivate) a country exclusivity agreement. PlatformAdmin only.

Revoke a previously granted addon. PlatformAdmin only. The grant record is kept (with enabled = false) so the audit trail of past activations is recoverable from the config history. A subsequent grant will overwrite it.

Revoke (deactivate) a region exclusivity agreement. PlatformAdmin only.

Set or clear the billing email override on a subscription (PlatformAdmin only).

Toggle cancel-at-period-end on a subscription (PlatformAdmin only).

Set or clear the grace-period end on a subscription (PlatformAdmin only).

Set or clear the pause end on a subscription (PlatformAdmin only).

Set or clear custom per-subscription limit overrides (PlatformAdmin only). Input must be a JSON object keyed by limit_id (e.g. {"max_drivers": 250}).

Replace the selected verticals on a subscription (PlatformAdmin only).

Set or clear the trial end date on a subscription (PlatformAdmin only).

Suspend a tenant (PlatformAdmin only).

Send a synchronous test notification to a channel. PlatformAdmin only. Returns true when the underlying HTTP call succeeded.

Unblock a blocked tenant (PlatformAdmin only). Restores the tenant to Active status.

Update a country exclusivity agreement. PlatformAdmin only.

Update an existing channel. PlatformAdmin only.

Update a region exclusivity agreement. PlatformAdmin only.

Override a subscription's status (PlatformAdmin only).

Update tenant fields (PlatformAdmin only).

Verify a pending registration's email. Moves status to EmailVerified so the user can log in and complete onboarding (plan selection + payment) themselves. Bypasses email token and expiry. PlatformAdmin only.

Forward the tenant wallet's credit (in currency) to the active subscription's PSP customer balance. Idempotent in the sense that repeated calls when the wallet is empty are no-ops.

Cancel all region exclusivities for the current tenant.

Cancel country exclusivity for a specific country.

Cancel region exclusivity for a specific city.

Cancel the current subscription.

Upgrade or downgrade the subscription plan.

Complete onboarding by subscribing to a plan. Creates the tenant, admin account, and subscription. Returns new authentication tokens for the created tenant admin.

Finalize a Stripe checkout without waiting for the webhook. The client calls this on return from checkout. We retrieve the session from Stripe, reject it if it hasn't completed + paid, then run the same provisioning the webhook does. If the webhook already processed it, this returns alreadyProcessed = true instead of double-provisioning. No GraphQL authentication required — the registration flow calls this before the tenant exists, so there's no session to bind to. The session_id itself is the authenticator: it's unguessable and Stripe only hands it out to the paying user, and the mutation can only produce side effects if the PSP confirms the session is complete + paid.

Create a new API key for the tenant. The plaintext key is returned only once. Store it securely. Requires Owner-tier (TenantOwner or PlatformAdmin) — issuing a long-lived backend credential is a danger-zone action.

Create a Stripe Billing Portal session. Returns the portal URL.

Create a connected app. * ownership = Platform — PlatformAdmin only, tenantId must be null. * ownership = Tenant — any admin, tenantId must be set (tenant admins may only create rows for their own tenant).

Create a Stripe checkout session for an email-verified registration. No tenant exists yet — the webhook will create it after payment. No authentication required (the registration_id serves as the identifier).

Soft-delete a connected app. Same authorization rules as update.

Opt the tenant out of a platform-owned app — it stops appearing in AASA / assetlinks for that tenant's domains.

Re-enable (i.e., remove from the opt-out set) a previously-disabled platform app for the tenant.

Validate a code without consuming it. Surfaces "already redeemed" so the UI can warn the user before they commit.

Provision (or sync) the store-review account. Three branches, see StoreReviewManagementUseCase docs: 1. Account missing → returns credentials (one-time plaintext). 2. Account exists, roles drifted → returns info + synced_roles. 3. Account exists, roles current → errors. Caller should switch to the password reset action.

Purchase country-level exclusivity for one or more countries.

Purchase region exclusivity for one or more cities. The tenant must have an active subscription and the cities must be in their operation areas. The exclusivity covers all verticals on the tenant's current subscription and lasts until cancelled or the subscription ends.

Reactivate a cancelled subscription (before period end).

Redeem a legacy purchase code, crediting the tenant wallet by the exact amount the customer originally paid. Single-use per code.

Register a new tenant. Sends a verification email to the admin. No authentication required.

Remove an addon from the current subscription.

Remove a custom domain. Only custom domains can be removed; system domains are managed automatically.

Remove a city from the current tenant's operation areas. This permanently drops the row from the allow-list. Use setOperationCityActive to soft-disable instead — disabled rows stay parked for one-click reactivation.

Remove branding for a specific vertical. Requires TenantAdmin role.

Resend the verification email for a pending registration. Rate limited: max 5 resends, 60s cooldown between resends. No authentication required.

Rotate the reviewer's password and return the new plaintext once. Errors with "store-review account not found" if the reviewer hasn't been provisioned yet.

Revoke all API keys for the tenant. All keys will immediately become invalid. Use with caution! Requires Owner-tier (TenantOwner or PlatformAdmin).

Revoke a single API key. The key will immediately become invalid for authentication. Requires Owner-tier (TenantOwner or PlatformAdmin).

Rollback branding to a previous version. Creates a new version with the content from the specified version. Requires TenantAdmin role.

Rotate an API key (revoke old and create new in one operation). This enables zero-downtime key rotation by creating the new key before revoking the old one. Requires Owner-tier (TenantOwner or PlatformAdmin) **and** a fresh step-up elevation token — rotation is a destructive security action that should be paired with a re-auth so a stolen Owner session can't quietly mint a long-lived key.

Save a tenant configuration (TenantAdmin for own tenant, PlatformAdmin for any). Creates a new versioned revision and sets it as current. Provide exactly one config variant via the @oneOf input.

Toggle the active state of an existing operation city. Activating a row enforces the plan locations limit (it consumes a slot). Deactivating frees the slot but keeps the row in the allow-list so the tenant can flip it back without rediscovering the city.

Toggle whether a tenant is publicly discoverable. Accessible by: - **TenantAdmin**: can toggle discoverability of their own tenant. - **PlatformAdmin**: can toggle discoverability of any tenant (pass tenant_id).

Toggle whether a tenant is a demo/test tenant. Demo tenants get relaxed auth and extra UI features. This is a platform-level setting and can only be changed by PlatformAdmin.

Set or update branding for a specific app within a vertical. Requires TenantAdmin role.

Set or update branding for a specific vertical. Requires TenantAdmin role.

Start the subscription flow. Creates a Stripe Checkout Session and returns the checkout URL. No subscription is saved until the checkout completes and the webhook fires.

Update the quantity of an existing addon.

Save a new revision of the tenant's AuthPolicy. Requires TenantAdmin (or PlatformAdmin impersonation). The payload replaces the rule set in full — there's no merge semantics, the version-bump-per-save pattern matches update_tier_config.

Update the entire branding configuration. Creates a new version and sets it as current. Requires TenantAdmin role.

Update only the company brand. Preserves existing vertical brands. Requires TenantAdmin role.

Update mutable fields on a connected app. Ownership and platform are immutable — delete + recreate if those need to change.

Update regional settings configuration. Sets locale, measurement system, time format, map defaults, wallet top-up presets, and support contact for the tenant. Creates a new version and sets it as current. Requires TenantAdmin role.

Save a new revision of the tenant's tier policy (display names, verification ladder, expiry days, strike thresholds, payment-method requirement). Requires TenantAdmin role.

Verify DNS for a custom domain by checking host resolution. The tenant must have already set up a CNAME record pointing the custom domain to the system subdomain. This mutation performs a basic DNS lookup to confirm the domain resolves. Full CNAME chain verification may be added later.

Verify a tenant registration email token. Marks the registration as EmailVerified — no tenant is created yet. The user must log in and complete onboarding (plan subscription) to become a real tenant. No authentication required.