@buildbase/sdk

A React SDK for BuildBase that provides essential components to build SaaS applications faster. Skip the plumbing and focus on your core product with built-in authentication, workspace management, billing, and more.

Also works server-side (Next.js API routes, Express, Hono) — see Server-Side Usage below.

📑 Table of Contents

• Features
• Installation
• Quick Start
• Authentication
• Redirect Preservation
• Affiliate / Referral Tracking
• Role-Based Access Control
• Feature Flags
• Subscription Gates
• Trial Gates
• Push Notifications
• Notifications
• User Management
• Workspace Management
• Public Pricing (No Login)
• Multi-Currency & Pricing Utilities
• Quota Usage Tracking
• Quota Gates
• Credit System
• Credit Gates
• Beta Form Component
• Event System
• Error Handling
• Settings
• Configuration Reference
• Common Patterns
• Troubleshooting
• API Reference
• Best Practices
• Server-Side Usage

🚀 Features

• 🔐 Authentication System - Complete auth flow with sign-in/sign-out and redirect preservation
• 🏢 Workspace Management - Multi-workspace support with switching capabilities
• 👥 Role-Based Access Control - User roles and workspace-specific permissions
• 🎯 Feature Flags - Workspace-level and user-level feature toggles
• 📋 Subscription Gates - Show or hide UI based on current workspace subscription (plan)
• ⏳ Trial Gates - WhenTrialing, WhenNotTrialing, WhenTrialEnding components + useTrialStatus hook
• 🔔 Push Notifications - Browser push notifications with usePushNotifications hook, auto-triggers for billing events, and campaign management
• 📬 Notifications - Email + push notification system with per-event channel control, workspace preferences, and server-side notification.send() API
• 💺 Seat-Based Pricing - Per-seat billing with included seats, billable seat tracking, and seat limit enforcement
• 💱 Multi-Currency - Per-currency pricing variants with workspace billing currency lock
• 🤝 Affiliate Tracking - Pass referral data to Stripe checkout via getCheckoutStripeParams prop (Rewardful, Endorsely, FirstPromoter, etc.)
• 📊 Quota Usage Tracking - Record and monitor metered usage (API calls, storage, etc.) with real-time status
• 📈 Usage Dashboard - Built-in workspace settings page showing quota consumption, overage billing breakdowns, and billing period info
• 👤 User Management - User attributes and feature flags management
• 📝 Beta Form - Pre-built signup/waitlist form component
• 📡 Event System - Subscribe to user and workspace events
• 🛡️ Error Handling - Centralized error handling with error boundaries
• 💳 Credit System - Prepaid credit balances with consume, credit gate components, and built-in workspace settings for purchasing and transaction history
• 🖥️ Server-Side SDK - BuildBase() factory for API routes, background jobs, Express, Hono — zero React dependency
• 🌐 Internationalization (i18n) - 8 locales (en, es, fr, de, ja, zh, hi, ar), ICU MessageFormat, RTL support, native numerals
• 🏠 Workspace Modes - Personal (solo B2C) or Platform (multi-user B2B), configured from admin dashboard

Installation

npm install @buildbase/sdk react@^19.0.0 react-dom@^19.0.0

Quick Start

1. Import CSS

// app/layout.tsx (or your root layout)
import '@buildbase/sdk/css';

2. Create Provider

// components/provider.tsx
'use client';

import { SaaSOSProvider } from '@buildbase/sdk/react';
import { ApiVersion } from '@buildbase/sdk';

export default function SaaSProvider({ children }: { children: React.ReactNode }) {
  return (
    <SaaSOSProvider
      serverUrl="https://your-api-server.com"
      version={ApiVersion.V1}
      orgId="your-org-id"
      auth={{
        clientId: 'your-client-id',
        redirectUrl: 'http://localhost:3000',
        callbacks: {
          // Called on page refresh to restore session from httpOnly cookie
          getSession: async () => {
            const res = await fetch('/api/auth/session');
            const data = await res.json();
            return data.sessionId ?? null;
          },

          // Called after OAuth redirect to exchange code for sessionId
          handleAuthentication: async code => {
            const res = await fetch('/api/auth/verify', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({ code }),
            });
            const data = await res.json();
            return { sessionId: data.sessionId };
          },

          // Called on sign out to clear the httpOnly cookie
          onSignOut: async () => {
            await fetch('/api/auth/signout', { method: 'POST' });
            window.location.reload();
          },

          handleEvent: (eventType, data) => {
            console.log('SDK Event:', eventType, data);
          },
          onWorkspaceChange: async ({ workspace, user, role }) => {
            console.log('Switching to:', workspace.name, 'as', role);
          },
        },
      }}
    >
      {children}
    </SaaSOSProvider>
  );
}

The SDK uses the same session pattern as next-auth: the session token lives in an httpOnly cookie (set by your server), and the SDK calls getSession() on page refresh to restore it. You need three server endpoints:

• /api/auth/verify — exchanges OAuth code for sessionId, sets httpOnly cookie
• /api/auth/session — reads httpOnly cookie, returns { sessionId } (called on page refresh)
• /api/auth/signout — clears the httpOnly cookie

3. Wrap Your App

// app/layout.tsx
import SaaSProvider from '@/components/provider';
import '@buildbase/sdk/css';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <SaaSProvider>{children}</SaaSProvider>
      </body>
    </html>
  );
}

4. Workspace Switcher

The WorkspaceSwitcher component uses a render prop pattern, giving you full control over the UI. Configure onWorkspaceChange in auth.callbacks (SaaSOSProvider) to handle workspace switches—used when clicking "Switch to" and when restoring from storage on page refresh. The callback receives { workspace, user, role } so you don't need to look up the user's role:

import React from 'react';
import { WorkspaceSwitcher } from '@buildbase/sdk/react';

function WorkspaceExample() {
  return (
    <WorkspaceSwitcher
      trigger={(isLoading, currentWorkspace) => {
        if (isLoading) {
          return <div>Loading...</div>;
        }

        if (!currentWorkspace) {
          return (
            <div className="flex items-center gap-2 min-w-40 border rounded-md p-2 hover:bg-muted cursor-pointer">
              <div className="bg-gray-200 flex aspect-square size-8 items-center justify-center rounded-lg"></div>
              <div className="grid flex-1 text-left text-sm leading-tight">Choose a workspace</div>
            </div>
          );
        }

        return (
          <div className="flex items-center gap-2 min-w-40 border rounded-md p-2 hover:bg-muted cursor-pointer">
            <div className="flex items-center justify-center h-full w-full bg-muted rounded-lg max-h-8 max-w-8">
              {currentWorkspace?.image && (
                <img src={currentWorkspace?.image} alt={currentWorkspace?.name} />
              )}
            </div>
            <div className="grid flex-1 text-left text-sm leading-tight">
              <span className="truncate font-medium">{currentWorkspace?.name}</span>
            </div>
          </div>
        );
      }}
    />
  );
}

🔐 Authentication

Authentication Hook

Use the useSaaSAuth hook to manage authentication state and actions:

import { useSaaSAuth } from '@buildbase/sdk/react';

function AuthExample() {
  const { user, isAuthenticated, signIn, signOut, status } = useSaaSAuth();

  return (
    <div>
      {!isAuthenticated ? (
        <div>
          <h1>Welcome! Please sign in</h1>
          <button onClick={() => signIn()} disabled={status === 'loading'}>
            {status === 'loading' ? 'Signing in...' : 'Sign In'}
          </button>
        </div>
      ) : (
        <div>
          <h1>Welcome back, {user?.name}!</h1>
          <p>Email: {user?.email}</p>
          <p>Role: {user?.role}</p>
          <button onClick={signOut}>Sign Out</button>
        </div>
      )}
    </div>
  );
}

Authentication Hook Properties

const {
  user, // Current user object (null if not authenticated)
  session, // Full session object with user and sessionId
  isAuthenticated, // Boolean: true if user is authenticated
  isLoading, // Boolean: true when checking authentication status
  isRedirecting, // Boolean: true when redirecting for OAuth
  status, // AuthStatus: 'loading' | 'redirecting' | 'authenticating' | 'authenticated' | 'unauthenticated' (use AuthStatus enum for type-safe checks)
  signIn, // Function: initiates sign-in flow. Accepts optional returnUrl to redirect back after login.
  signOut, // Function: signs out the user
  openWorkspaceSettings, // Function: opens workspace settings dialog to a specific section
} = useSaaSAuth();

Workspace Settings Sections

Open the workspace settings dialog to a specific section:

openWorkspaceSettings('profile'); // Account profile
openWorkspaceSettings('general'); // Workspace name, icon
openWorkspaceSettings('users'); // Workspace members
openWorkspaceSettings('subscription'); // Plan & Billing
openWorkspaceSettings('usage'); // Quota usage dashboard
openWorkspaceSettings('features'); // Feature toggles
openWorkspaceSettings('danger'); // Delete workspace (owner only)

Authentication Components

For declarative rendering, use the conditional components:

import { WhenAuthenticated, WhenUnauthenticated } from '@buildbase/sdk/react';

function App() {
  return (
    <div>
      <WhenUnauthenticated>
        <LoginPage />
      </WhenUnauthenticated>

      <WhenAuthenticated>
        <Dashboard />
      </WhenAuthenticated>
    </div>
  );
}

Redirect Preservation

The SDK automatically preserves the URL when signIn() is called. After login, the user is redirected back to the page they were on.

// Automatic — just call signIn(), the current URL is saved
signIn();

// Custom — pass a specific URL to redirect to after login
signIn('https://app.com/dashboard?bb=action:selectPlan,plan:abc');

This works across the full OAuth round-trip via localStorage (10-minute TTL, validated with validateRedirectUrl()).

For advanced use cases, the low-level helpers are also exported:

import { saveAuthIntent, consumeAuthIntent, clearAuthIntent } from '@buildbase/sdk';

Affiliate / Referral Tracking

Pass affiliate/referral data to Stripe checkout sessions via the getCheckoutStripeParams prop on SaaSOSProvider. This async callback is called before every checkout session is created, so you can fetch referral IDs, read cookies, or call any async API:

<SaaSOSProvider
  serverUrl="https://your-api-server.com"
  version={ApiVersion.V1}
  orgId="your-org-id"
  auth={authConfig}
  getCheckoutStripeParams={async request => {
    // Rewardful, FirstPromoter, PartnerStack — read client_reference_id
    const referralId = await getRewardfulReferralId();

    return {
      clientReferenceId: referralId,

      // Endorsely — reads subscription metadata
      subscriptionMetadata: { endorsely_referral: window.endorsely_referral },

      // Custom tracking on the checkout session
      metadata: { campaign: 'summer-sale' },
    };
  }}
>
  <App />
</SaaSOSProvider>

The returned object is merged into the Stripe checkout session. You can return any combination of the fields below, or undefined to proceed without extra options:

| Field | Stripe mapping | Use case | | ---------------------- | ----------------------------- | -------------------------------------- | | clientReferenceId | client_reference_id | Rewardful, FirstPromoter, etc. | | metadata | metadata (checkout session) | Custom tracking, Endorsely | | subscriptionMetadata | subscription_data.metadata | Data that persists on the subscription |

👥 Role-Based Access Control

Role Components

Control access based on user roles:

import { WhenRoles, WhenWorkspaceRoles } from '@buildbase/sdk/react';

function AdminPanel() {
  return (
    <div>
      {/* Global user roles */}
      <WhenRoles roles={['admin', 'super-admin']}>
        <AdminControls />
      </WhenRoles>

      {/* Workspace-specific roles */}
      <WhenWorkspaceRoles roles={['owner', 'admin']}>
        <WorkspaceSettings />
      </WhenWorkspaceRoles>

      {/* With fallback content */}
      <WhenRoles roles={['admin']} fallback={<p>You need admin access to view this content</p>}>
        <SensitiveData />
      </WhenRoles>
    </div>
  );
}

🎛️ Feature Flags

Control feature visibility based on workspace and user settings:

import {
  WhenWorkspaceFeatureEnabled,
  WhenWorkspaceFeatureDisabled,
  WhenUserFeatureEnabled,
  WhenUserFeatureDisabled,
} from '@buildbase/sdk/react';

function FeatureExample() {
  return (
    <div>
      {/* Workspace-level features */}
      <WhenWorkspaceFeatureEnabled slug="advanced-analytics">
        <AdvancedAnalytics />
      </WhenWorkspaceFeatureEnabled>

      <WhenWorkspaceFeatureDisabled slug="beta-features">
        <p>Beta features are not enabled for this workspace</p>
      </WhenWorkspaceFeatureDisabled>

      {/* User-level features */}
      <WhenUserFeatureEnabled slug="premium-features">
        <PremiumDashboard />
      </WhenUserFeatureEnabled>

      <WhenUserFeatureDisabled slug="trial-mode">
        <UpgradePrompt />
      </WhenUserFeatureDisabled>
    </div>
  );
}

Feature Flags Hook

Use the useUserFeatures hook to check feature flags programmatically:

import { useUserFeatures } from '@buildbase/sdk/react';

function FeatureCheck() {
  const { features, isFeatureEnabled, refreshFeatures } = useUserFeatures();

  return (
    <div>{isFeatureEnabled('premium-features') ? <PremiumContent /> : <StandardContent />}</div>
  );
}

📋 Subscription Gates

Control UI visibility based on the current workspace’s subscription. Subscription data is loaded once per workspace and refetched when the workspace changes or when the subscription is updated (e.g. upgrade, cancel, resume).

SubscriptionContextProvider is included in SaaSOSProvider by default, so subscription gates work without extra setup.

Subscription Gate Components

import {
  WhenSubscription,
  WhenNoSubscription,
  WhenSubscriptionToPlans,
} from '@buildbase/sdk/react';

function BillingExample() {
  return (
    <div>
      {/* Show when workspace has any active subscription */}
      <WhenSubscription>
        <BillingSettings />
      </WhenSubscription>

      {/* Show when workspace has no subscription */}
      <WhenNoSubscription>
        <UpgradePrompt />
      </WhenNoSubscription>

      {/* Show only when subscribed to specific plans (by slug, case-insensitive) */}
      <WhenSubscriptionToPlans plans={['pro', 'enterprise']}>
        <AdvancedAnalytics />
      </WhenSubscriptionToPlans>
    </div>
  );
}

| Component | Renders when | | ------------------------- | -------------------------------------------------------------------- | | WhenSubscription | Current workspace has an active subscription (any plan); not loading | | WhenNoSubscription | Current workspace has no subscription (or no workspace); not loading | | WhenSubscriptionToPlans | Current workspace is subscribed to one of the given plan slugs |

All gates must be used inside SubscriptionContextProvider (included in SaaSOSProvider). By default they return null while loading or when the condition is not met. You can pass optional loadingComponent (component/element to show while loading) and fallbackComponent (component/element to show when condition is not met):

<WhenSubscription
  loadingComponent={<Skeleton className="h-20" />}
  fallbackComponent={<UpgradePrompt />}
>
  <BillingSettings />
</WhenSubscription>

<WhenSubscriptionToPlans
  plans={['pro', 'enterprise']}
  loadingComponent={<Spinner />}
  fallbackComponent={<p>Upgrade to Pro or Enterprise to access this feature.</p>}
>
  <AdvancedAnalytics />
</WhenSubscriptionToPlans>

useSubscriptionContext

Use the hook when you need subscription data or a manual refetch (e.g. after returning from Stripe checkout):

import { useSubscriptionContext } from '@buildbase/sdk/react';

function SubscriptionStatus() {
  const { response, loading, refetch } = useSubscriptionContext();

  if (loading) return <Spinner />;
  if (!response?.subscription) return <p>No active subscription</p>;

  const plan = response.plan ?? response.subscription?.plan;
  return (
    <div>
      <p>Plan: {plan?.name ?? plan?.slug}</p>
      <button onClick={() => refetch()}>Refresh</button>
    </div>
  );
}

| Property | Type | Description | | ---------- | ------------------------------- | ------------------------------------------------------ | | response | ISubscriptionResponse \| null | Current subscription data for the current workspace | | loading | boolean | True while subscription is being fetched | | refetch | () => Promise<void> | Manually refetch subscription (e.g. after plan change) |

When subscription refetches

• When the current workspace changes (automatic).
• When subscription is updated via SDK (e.g. useUpdateSubscription, cancel, resume) — refetch is triggered automatically.
• When you call refetch() (e.g. after redirect from checkout).

⏳ Trial Gates

Control UI based on trial state. Works with Stripe-native trials (both card-required and no-card).

Trial Gate Components

import { WhenTrialing, WhenNotTrialing, WhenTrialEnding } from '@buildbase/sdk/react';

function TrialExample() {
  return (
    <div>
      {/* Show only during active trial */}
      <WhenTrialing>
        <TrialBanner />
      </WhenTrialing>

      {/* Show when NOT trialing (active, canceled, or no subscription) */}
      <WhenNotTrialing>
        <RegularContent />
      </WhenNotTrialing>

      {/* Show when trial ends within N days (default: 3) */}
      <WhenTrialEnding daysThreshold={7}>
        <UpgradeUrgentBanner />
      </WhenTrialEnding>
    </div>
  );
}

| Component | Renders when | | ----------------- | --------------------------------------------------------------- | | WhenTrialing | Subscription status is trialing | | WhenNotTrialing | Subscription status is NOT trialing | | WhenTrialEnding | Trialing AND trial ends within daysThreshold days (default 3) |

All trial gates support loadingComponent and fallbackComponent props.

useTrialStatus

Hook that computes trial information from the subscription context:

import { useTrialStatus } from '@buildbase/sdk/react';

function TrialInfo() {
  const { isTrialing, daysRemaining, trialEndsAt, isTrialEnding } = useTrialStatus();

  if (!isTrialing) return null;

  return (
    <div>
      <p>Trial ends in {daysRemaining} days</p>
      {isTrialEnding && <p>Upgrade now to keep access!</p>}
    </div>
  );
}

| Property | Type | Description | | ---------------- | -------------- | ------------------------------------------------- | | isTrialing | boolean | Whether subscription is in trial | | daysRemaining | number | Days left in trial (0 if not trialing or expired) | | trialEndsAt | Date \| null | Trial end date | | trialStartedAt | Date \| null | Trial start date | | isTrialEnding | boolean | True when 3 or fewer days remaining |

🔔 Push Notifications

Browser push notifications — built into the SDK. Users can enable/disable from the Notifications tab in workspace settings. Billing events (payment failed, trial ending) auto-send push notifications.

Only setup required: Create public/push-sw.js in your app:

self.addEventListener('push', function (event) {
  if (!event.data) return;
  try {
    var payload = event.data.json();
    var options = {
      body: payload.body || '',
      icon: payload.icon || undefined,
      badge: payload.badge || payload.icon || undefined,
      image: payload.image || undefined,
      tag: payload.tag || undefined,
      actions: payload.actions || undefined,
      silent: payload.silent || false,
      requireInteraction: payload.requireInteraction || false,
      renotify: payload.renotify || false,
      timestamp: payload.timestamp || undefined,
      dir: payload.dir || 'auto',
      data: { url: payload.url, ...(payload.data || {}) },
    };
    event.waitUntil(self.registration.showNotification(payload.title || 'Notification', options));
  } catch (e) {
    console.error('[PushSW]', e);
  }
});

self.addEventListener('notificationclick', function (event) {
  event.notification.close();
  var url = event.notification.data && event.notification.data.url;
  if (url) {
    event.waitUntil(
      clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function (list) {
        for (var i = 0; i < list.length; i++) {
          if (list[i].url === url && 'focus' in list[i]) return list[i].focus();
        }
        if (clients.openWindow) return clients.openWindow(url);
      })
    );
  }
});

Everything else is built-in — permission handling, subscribe/unsubscribe, settings UI, billing auto-triggers, and browser-specific unblock instructions.

📬 Notifications

Send email and push notifications to workspace members. The system has three layers:

• System notifications — Automatically triggered by platform events (workspace invite, payment failed, trial ending, etc.). Managed by the developer in the admin dashboard.
• Custom notifications — Defined by the developer, triggered from app code via SDK. Can be made user-configurable.
• Ad-hoc notifications — Send push notifications with any event slug without pre-registering it. No event setup needed — just pass title, message, and optionally icon, image, url. Email requires a registered event with a linked template.

Sending Notifications (Server-Side)

import { notification } from '@/lib/buildbase';

// Notify a specific user
await notification.send(workspaceId, 'comment_added', userId, {
  title: 'New Comment', // Push title (falls back to event name)
  message: 'Alice commented on your project', // Push body + email {{message}}
  icon: 'https://example.com/comment-icon.png', // Custom push icon (falls back to org icon)
  image: 'https://example.com/screenshot.jpg', // Large image in push notification body
  url: 'https://app.example.com/projects/123#comments', // Opens on push click + {{url}} in email
});

// Notify all workspace members (omit userId)
await notification.send(workspaceId, 'new_release', undefined, {
  title: 'New Release',
  message: 'Version 2.0 is now available with dark mode and API v2!',
  image: 'https://example.com/release-banner.jpg',
  url: 'https://app.example.com/changelog',
});

Ad-hoc Notifications

Send push notifications without creating a custom event first — any event slug works:

// No need to register 'deployment_success' as a custom event
await notification.send(workspaceId, 'deployment_success', userId, {
  title: 'Deployment Complete',
  message: 'v2.1.0 deployed to production',
  icon: 'https://example.com/deploy-icon.png',
  url: '/deployments/latest',
  channels: { push: true },
});

Note: Ad-hoc events support push only. Email requires a registered event with a linked email template.

Push Options

Fine-grained control over push notification behavior:

// Action buttons — user can tap "Reply" or "Dismiss" directly on the notification
await notification.send(workspaceId, 'new_message', userId, {
  title: 'New message from Alice',
  message: 'Hey, are you free for a call?',
  actions: [
    { action: 'reply', title: 'Reply', icon: 'https://example.com/reply.png' },
    { action: 'dismiss', title: 'Dismiss' },
  ],
  tag: 'chat-alice', // Replaces previous "chat-alice" notification instead of stacking
  renotify: true, // Still vibrate/sound when replacing
  channels: { push: true },
});

// Critical alert — stays visible until user interacts
await notification.send(workspaceId, 'payment_failed', userId, {
  title: 'Payment Failed',
  message: 'Your subscription will be suspended in 3 days',
  badge: 'https://example.com/alert-badge.png',
  requireInteraction: true, // No auto-dismiss
  urgency: 'high', // Prioritized delivery on mobile
  channels: { push: true },
});

// Silent notification — no sound or vibration
await notification.send(workspaceId, 'sync_complete', userId, {
  title: 'Sync Complete',
  message: '1,234 records synced',
  silent: true,
  urgency: 'low',
  channels: { push: true },
});

| Option | Type | Description | | -------------------- | ------------------------------- | ---------------------------------------------------------------- | | badge | string | Small monochrome icon for status bar (Android/ChromeOS) | | tag | string | Replaces existing notification with same tag instead of stacking | | actions | Array<{action, title, icon?}> | Up to 2 action buttons on the notification | | silent | boolean | No sound or vibration | | requireInteraction | boolean | Stays visible until user interacts | | renotify | boolean | Sound/vibrate again when replacing via tag | | timestamp | number | Custom timestamp (ms since epoch) shown on notification | | dir | 'ltr' \| 'rtl' \| 'auto' | Text direction for title/body |

Delivery Options

Control how and when the push service delivers the notification:

// Schedule for later
await notification.send(workspaceId, 'daily_digest', undefined, {
  title: 'Your Daily Digest',
  message: '12 new updates in your workspace',
  scheduledAt: '2026-04-16T09:00:00Z', // Deliver at 9am UTC tomorrow
  channels: { push: true },
});

// Short-lived notification — discard if not delivered in 1 hour
await notification.send(workspaceId, 'flash_sale', undefined, {
  title: 'Flash Sale — 50% off!',
  message: 'Ends in 1 hour',
  image: 'https://example.com/sale-banner.jpg',
  ttl: 3600, // Expires after 1 hour (seconds)
  urgency: 'high', // Deliver ASAP
  channels: { push: true },
});

| Option | Type | Description | | ------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------- | | scheduledAt | string | ISO 8601 date. Delays delivery until the specified time | | ttl | number | Time-to-live in seconds. Push service discards if not delivered in time. Default: 86400 (24h) | | urgency | 'very-low' \| 'low' \| 'normal' \| 'high' | Delivery priority hint. Affects battery usage on mobile |

Channel Control

By default, both email and push are sent (based on event config). Override per-send with channels:

// Only push — real-time alert, no email
await notification.send(workspaceId, 'typing_indicator', userId, {
  message: 'Alice is typing...',
  channels: { push: true },
});

// Only email — digest or report, no push
await notification.send(workspaceId, 'weekly_report', undefined, {
  message: 'Your weekly activity report is ready',
  channels: { email: true },
});

// Both channels explicitly
await notification.send(workspaceId, 'comment_added', userId, {
  message: 'New comment on your project',
  channels: { email: true, push: true },
});

Note: Even with channels override, the 4-layer gate still applies. If the admin disabled push globally, channels: { push: true } won't send push.

Merge Tags

Both email and push support merge tags with {{tag}} syntax:

await notification.send(workspaceId, 'export_ready', userId, {
  title: '{{workspaceName}} — Export Ready', // → "Acme Corp — Export Ready"
  message: 'Hi {{name}}, your export is ready', // → "Hi Alice, your export is ready"
  downloadUrl: 'https://example.com/exports/123',
  fileName: 'report.csv',
});

| Tag | Resolves to | Available in | | ------------------- | ------------------------ | ---------------------------------- | | {{name}} | Recipient's name | Email + Push | | {{email}} | Recipient's email | Email + Push | | {{workspaceName}} | Workspace name | Email + Push | | {{message}} | The message field | Email template | | {{url}} | The url field | Email template + Push click target | | {{anyKey}} | Value from data object | Email + Push |

Response

{
  sent: true,
  channels: { email: true, push: true },
  notifiedCount: 5  // Number of users notified (1 for single user, N for workspace)
}

How It Works

When notification.send() is called, the system checks 4 layers before delivering:

1. Org global settings — Developer can disable all email or all push notifications globally
2. Event config — Per-event enabled/disabled and per-channel (email/push) toggles
3. Workspace preferences — End-user overrides (only for events marked userManaged)
4. User unsubscribe — Per-user email unsubscribe preferences (checked at delivery time)

Creating Custom Events

Custom notification events are created in the admin dashboard under Notifications > Custom:

• Name — Display name (e.g., "Comment Added")
• Slug — Used in code (e.g., comment_added)
• Category — Grouping in settings UI (e.g., "Activity")
• Channels — Enable/disable email and push per event
• User Control — If enabled, workspace members can toggle this notification in their settings

An email template is auto-created for each custom event. Edit it in Email Templates to customize the content and add merge tags like {{downloadUrl}}, {{commentText}}, etc.

Notification Settings (End-User UI)

The workspace settings panel shows notification preferences automatically — only for events where the developer enabled "User Control". System notifications are never shown to end users.

import { SaaSOSProvider } from '@buildbase/sdk/react';

// The Notifications tab in workspace settings shows:
// - Browser push toggle (subscribe/unsubscribe)
// - Per-event email/push toggles (only user-manageable custom events)

Notification Types

import type { NotificationData, NotificationResult, NotificationEvent } from '@buildbase/sdk';

interface NotificationData {
  title?: string; // Push title (falls back to event name)
  message?: string; // Push body + email {{message}}
  icon?: string; // Custom push icon URL (falls back to org icon)
  image?: string; // Large image in push notification body
  badge?: string; // Small monochrome status bar icon
  url?: string; // Opens on push click + {{url}} in email
  tag?: string; // Replace instead of stack notifications
  actions?: Array<{ action; title; icon? }>; // Action buttons (max 2)
  silent?: boolean; // No sound/vibration
  requireInteraction?: boolean; // No auto-dismiss
  renotify?: boolean; // Re-alert on tag replace
  timestamp?: number; // Custom timestamp (ms)
  dir?: 'ltr' | 'rtl' | 'auto'; // Text direction
  ttl?: number; // Time-to-live (seconds)
  urgency?: 'very-low' | 'low' | 'normal' | 'high'; // Delivery priority
  scheduledAt?: string; // ISO 8601 delayed delivery
  channels?: { email?: boolean; push?: boolean }; // Override which channels to use
  [key: string]: any; // Custom merge tags for email + push
}

interface NotificationResult {
  sent: boolean;
  channels: { email: boolean; push: boolean };
  notifiedCount?: number;
  reason?: string; // Only when sent=false
}

interface NotificationEvent {
  slug: string;
  name: string;
  description: string;
  category: string;
  channels: { email: boolean; push: boolean };
}

🌐 Internationalization (i18n)

The SDK supports 8 locales with ICU MessageFormat for plurals, selects, and number formatting.

Setup

<SaaSOSProvider locale="hi">{/* All SDK UI renders in Hindi */}</SaaSOSProvider>

Supported Locales

| Code | Language | Numerals | Direction | | ---- | -------- | ------------------------- | --------- | | en | English | 1,234.56 | LTR | | es | Spanish | 1.234,56 | LTR | | fr | French | 1 234,56 | LTR | | de | German | 1.234,56 | LTR | | ja | Japanese | 1,234.56 | LTR | | zh | Chinese | 1,234.56 | LTR | | hi | Hindi | Devanagari (e.g. 1,234) | LTR | | ar | Arabic | Arabic-Indic (e.g. 1,234) | RTL |

useTranslation Hook

import { useTranslation } from '@buildbase/sdk/react';

function MyComponent() {
  const { t, locale, dir, fmtNum, fmtCents } = useTranslation();

  return (
    <div dir={dir}>
      <p>{t('subscription.currentPlan')}</p> {/* Type-safe key lookup */}
      <p>{t('users.memberCount', { count: 5 })}</p> {/* ICU plural: "5 members" */}
      <p>{fmtNum(1234)}</p> {/* Locale-aware: "1,234" or "1,234" */}
      <p>{fmtCents(1999, 'usd')}</p> {/* "$19.99" or "19.99 US$" */}
    </div>
  );
}

Features

• ICU MessageFormat — plurals ({count, plural, one {# item} other {# items}}), selects, number formatting
• Type-safe keys — TranslationKey union type with autocomplete, catches typos at compile time
• Native numerals — Hindi uses Devanagari digits, Arabic uses Arabic-Indic digits
• RTL support — dir attribute on all dialogs, logical CSS properties (start/end instead of left/right)
• Locale-aware formatting — dates, currencies, and numbers formatted per locale
• Memoized Intl formatters — shared Intl.NumberFormat/DateTimeFormat/PluralRules instances for performance
• Lazy-loaded translations — non-English locales loaded on demand, English always bundled

🏠 Workspace Modes

The SDK supports two workspace modes, configured from the admin dashboard (no code changes needed):

Personal Mode

For B2C solo tools (Todoist, Grammarly, personal dashboards):

• 1 user = 1 auto-created workspace
• No team invites, no workspace switcher
• Clicking workspace trigger opens Settings directly
• Seats, members, roles sections hidden in UI
• Enforced at API level — workspace creation and invites blocked

Platform Mode (Default)

For full SaaS platforms (Slack, GitHub, Discord):

• Multi-workspace, multi-user
• Create workspaces, invite members, switch between them
• Full settings UI with members, roles, billing, seats

Advanced Overrides

Platform mode supports granular overrides from the admin dashboard:

| Setting | Options | Default | | --------------------------- | -------------------------------- | -------- | | Can Create Workspace | Everyone / Owner Only / Disabled | Everyone | | Can Invite Members | Everyone / Admin Only / Disabled | Everyone | | Show Workspace Switcher | On / Off | On | | Max Workspaces Per User | 0 (unlimited) or a number | 0 | | Auto-Create First Workspace | On / Off | On |

These let you achieve team-like, managed, or enterprise-like behavior without a separate mode.

👤 User Management

User Attributes

Manage custom user attributes (key-value pairs):

import { useUserAttributes } from '@buildbase/sdk/react';

function UserProfile() {
  const { attributes, isLoading, updateAttribute, updateAttributes, refreshAttributes } =
    useUserAttributes();

  const handleUpdate = async () => {
    // Update single attribute
    await updateAttribute('theme', 'dark');

    // Or update multiple attributes
    await updateAttributes({
      theme: 'dark',
      notifications: true,
      language: 'en',
    });
  };

  return (
    <div>
      <p>Theme: {attributes.theme}</p>
      <button onClick={handleUpdate}>Update Preferences</button>
    </div>
  );
}

🏢 Complete Workspace Management

The useSaaSWorkspaces hook provides comprehensive workspace management:

import { useSaaSWorkspaces } from '@buildbase/sdk/react';

function WorkspaceManager() {
  const {
    workspaces, // Array of all workspaces
    currentWorkspace, // Currently selected workspace
    loading, // Loading state
    refreshing, // Refreshing state
    switching, // True when a workspace switch is in progress
    switchingToId, // Workspace ID currently being switched to (null when not switching)
    error, // Error message
    fetchWorkspaces, // Fetch all workspaces
    refreshWorkspaces, // Background refresh
    setCurrentWorkspace, // Direct workspace set (bypasses onWorkspaceChange)
    switchToWorkspace, // Full switch flow: onWorkspaceChange first, then set workspace
    createWorkspace, // Create new workspace
    updateWorkspace, // Update workspace
    deleteWorkspace, // Delete workspace
    getUsers, // Get workspace users
    addUser, // Add user to workspace
    removeUser, // Remove user from workspace
    updateUser, // Update user role/permissions
    getFeatures, // Get all available features
    updateFeature, // Toggle workspace feature
    getProfile, // Get current user profile
    updateUserProfile, // Update user profile
    updateWorkspaceSettings, // Update workspace settings
    updateWorkspacePermissions, // Update workspace permissions
  } = useSaaSWorkspaces();

  // Example: Create a workspace
  const handleCreate = async () => {
    await createWorkspace('My Workspace', 'https://example.com/logo.png');
  };

  // Example: Add user to workspace
  const handleAddUser = async () => {
    await addUser(currentWorkspace._id, '[email protected]', 'member');
  };

  return <div>{/* Your workspace UI */}</div>;
}

💰 Public Pricing (No Login)

Display subscription plans and pricing on public pages (e.g. marketing site, pricing page) without requiring users to log in.

usePublicPlans

Fetches public plans by slug. Returns items (features, limits, quotas) and plans (with pricing). You construct the layout from this data:

import { usePublicPlans } from '@buildbase/sdk/react';

function PublicPricingPage() {
  const { items, plans, loading, error } = usePublicPlans('main-pricing');

  if (loading) return <Loading />;
  if (error) return <Error message={error} />;

  return (
    <div>
      {plans.map(plan => (
        <PlanCard key={plan._id} plan={plan} items={items} />
      ))}
    </div>
  );
}

PricingPage Component

Use the PricingPage component with a render-prop pattern:

import { PricingPage } from '@buildbase/sdk/react';

function PublicPricingPage() {
  return (
    <PricingPage slug="main-pricing" redirectBaseUrl="https://app.com/dashboard">
      {({ loading, error, items, plans, selectPlan, refetch }) => {
        if (loading) return <Loading />;
        if (error) return <Error message={error} />;

        return (
          <div>
            {plans.map(plan => (
              <div key={plan._id}>
                <PlanCard plan={plan} items={items} />
                <button onClick={() => selectPlan(plan._id, 'monthly', 'usd')}>
                  {plan.trial?.enabled
                    ? `Start ${plan.trial.durationDays}-Day Trial`
                    : 'Select Plan'}
                </button>
              </div>
            ))}
          </div>
        );
      }}
    </PricingPage>
  );
}

selectPlan() handles everything automatically:

• Authenticated → opens the "Choose Your Plan" dialog
• Not authenticated → saves a redirect URL, triggers sign-in, and after login the user lands on the dashboard with the plan picker dialog open

| Prop | Type | Description | | ----------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | slug | string | Plan group slug (e.g. 'main-pricing', 'enterprise') | | children | (details) => ReactNode | Render prop receiving plan details (see below) | | redirectBaseUrl | string | Base URL for post-login redirects (e.g. "https://app.com/dashboard"). Enables selectPlan() for unauthenticated users. | | loadingFallback | ReactNode | Custom loading UI (defaults to skeleton) | | errorFallback | (error: string) => ReactNode | Custom error UI |

Render prop details: { loading, error, items, plans, notes, refetch, selectPlan }

• selectPlan(planVersionId, interval, currency) — One-call plan selection (handles auth + dialog automatically)

Response shape: items = subscription item definitions (features, limits, quotas with category); plans = plan versions with pricing, quotas, features, limits.

Backend requirement: GET /api/v1/public/{orgId}/plans/{groupSlug} must be implemented and allow unauthenticated access.

💱 Multi-Currency & Pricing Utilities

Plans support pricing variants (multi-currency). Use these utilities for display and lookup.

Currency utilities

| Export | Purpose | | ------------------------------------ | --------------------------------------------------------- | | CURRENCY_DISPLAY | Map of currency code → symbol (e.g. usd → $) | | CURRENCY_FLAG | Map of currency code → flag emoji | | PLAN_CURRENCY_CODES | Allowed billing currency codes (for dropdowns/validation) | | PLAN_CURRENCY_OPTIONS | Options array for plan currency selects | | getCurrencySymbol(currency) | Symbol for a Stripe currency code | | getCurrencyFlag(currency) | Flag emoji for a currency code | | formatCents(cents, currency) | Format cents as localized price string | | formatOverageRate(cents, currency) | Format overage rate for display | | formatOverageRateWithLabel(...) | Overage rate with optional unit label | | formatQuotaIncludedOverage(...) | "X included, then $Y / unit" style text | | getQuotaUnitLabelFromName(name) | Human-readable unit label from quota name |

Pricing variant utilities

| Export | Purpose | | ------------------------------------------------------------------------ | ------------------------------------------------------------ | | getPricingVariant(planVersion, currency) | Get variant for a currency, or null | | getBasePriceCents(planVersion, currency, interval) | Base price in cents for currency/interval | | getStripePriceIdForInterval(planVersion, currency, interval) | Stripe price ID for checkout | | getQuotaOverageCents(planVersion, currency, quotaSlug, interval) | Overage cents for a quota | | getQuotaDisplayWithVariant(planVersion, currency, quotaSlug, interval) | Display value with overage for a variant | | getAvailableCurrenciesFromPlans(plans) | Unique currency codes across plan versions | | getDisplayCurrency(planVersion, currency) | Display currency (variant exists ? currency : plan.currency) | | getBillingIntervalAndCurrencyFromPriceId(planVersions, priceId) | Resolve price ID to interval + currency |

Types: IPricingVariant, PlanVersionWithPricingVariants, QuotaDisplayWithOverage.

Quota utilities

| Export | Purpose | | -------------------------------------------------- | ------------------------------------------------------------------- | | getQuotaDisplayValue(quotaByInterval, interval?) | Normalize IQuotaByInterval to { included, overage?, unitSize? } | | formatQuotaWithPrice(value, unitName, options?) | Format as "X included, then $Y.YY / unit" |

Types: QuotaDisplayValue, FormatQuotaWithPriceOptions. Plan/subscription types use IQuotaByInterval and IQuotaIntervalValue for per-interval quotas and overages.

import {
  getCurrencySymbol,
  formatCents,
  getPricingVariant,
  getBasePriceCents,
  getQuotaDisplayValue,
  formatQuotaWithPrice,
} from '@buildbase/sdk/react';

// Display price for a plan version in a currency
const variant = getPricingVariant(planVersion, 'usd');
const cents = getBasePriceCents(planVersion, 'usd', 'monthly');
if (cents != null) {
  console.log(getCurrencySymbol('usd') + (cents / 100).toFixed(2));
}

// Quota display with overage
const display = getQuotaDisplayValue(planVersion.quotas?.videos, 'monthly');
const text = formatQuotaWithPrice(display, 'video', { currency: 'usd' });

📊 Quota Usage Tracking

Track and monitor metered usage for subscription quotas (e.g., API calls, emails, storage). Usage can be recorded from both the client-side (React app) and server-side (your backend).

When to use which?

| Scenario | Where to record | Why | | ------------------------------- | ---------------------- | -------------------------------------------- | | User clicks "Send Email" button | Client-side (SDK hook) | User-initiated, immediate UI feedback needed | | API request hits your backend | Server-side (REST API) | Backend controls the resource, more secure | | Background job processes data | Server-side (REST API) | No browser context available | | File upload completes | Either | Depends on where validation happens |

As a general rule: record usage where the resource is consumed. If your backend processes the work, record from the backend. If it's a client-side action, record from the client.

Client-Side (React SDK)

Use the SDK hooks inside your React app. Quota gate components (see Quota Gates) automatically refresh after recording.

Record Usage

import { useRecordUsage, useSaaSWorkspaces } from '@buildbase/sdk/react';

function SendEmailButton() {
  const { currentWorkspace } = useSaaSWorkspaces();
  const { recordUsage, loading, error } = useRecordUsage(currentWorkspace?._id);

  const handleSend = async () => {
    try {
      const result = await recordUsage({
        quotaSlug: 'emails',
        quantity: 1,
        source: 'web-app', // optional: track where usage came from
        idempotencyKey: 'email-abc', // optional: prevent duplicate recordings
      });
      console.log(`Used: ${result.consumed}/${result.included}, Available: ${result.available}`);
      if (result.overage > 0) {
        console.warn(`Overage: ${result.overage} units`);
      }
    } catch (err) {
      console.error('Failed to record usage:', err);
    }
  };

  return (
    <button onClick={handleSend} disabled={loading}>
      Send Email
    </button>
  );
}

Check Single Quota Status

import { useQuotaUsageStatus, useSaaSWorkspaces } from '@buildbase/sdk/react';

function QuotaStatusBar({ quotaSlug }: { quotaSlug: string }) {
  const { currentWorkspace } = useSaaSWorkspaces();
  const { status, loading, refetch } = useQuotaUsageStatus(currentWorkspace?._id, quotaSlug);

  if (loading) return <Spinner />;
  if (!status) return null;

  const usagePercent = Math.round((status.consumed / status.included) * 100);

  return (
    <div>
      <p>
        {quotaSlug}: {status.consumed} / {status.included} ({usagePercent}%)
      </p>
      <p>Available: {status.available}</p>
      {status.hasOverage && <p>Overage: {status.overage} units</p>}
      <button onClick={refetch}>Refresh</button>
    </div>
  );
}

Check All Quotas

import { useAllQuotaUsage, useSaaSWorkspaces } from '@buildbase/sdk/react';

function QuotaDashboard() {
  const { currentWorkspace } = useSaaSWorkspaces();
  const { quotas, loading, refetch } = useAllQuotaUsage(currentWorkspace?._id);

  if (loading) return <Spinner />;
  if (!quotas) return <p>No quota data available</p>;

  return (
    <div>
      {Object.entries(quotas).map(([slug, usage]) => (
        <div key={slug}>
          <strong>{slug}</strong>: {usage.consumed} / {usage.included}
          {usage.hasOverage && <span> (overage: {usage.overage})</span>}
        </div>
      ))}
    </div>
  );
}

Usage Logs

import { useUsageLogs, useSaaSWorkspaces } from '@buildbase/sdk/react';

function UsageLogsTable() {
  const { currentWorkspace } = useSaaSWorkspaces();
  const { logs, totalDocs, totalPages, page, hasNextPage, loading, refetch } = useUsageLogs(
    currentWorkspace?._id,
    'api_calls', // optional: filter by quota slug
    { limit: 20, page: 1 } // optional: pagination and filters
  );

  if (loading) return <Spinner />;

  return (
    <div>
      <table>
        <thead>
          <tr>
            <th>Quota</th>
            <th>Quantity</th>
            <th>Source</th>
            <th>Date</th>
          </tr>
        </thead>
        <tbody>
          {logs.map(log => (
            <tr key={log._id}>
              <td>{log.quotaSlug}</td>
              <td>{log.quantity}</td>
              <td>{log.source ?? '-'}</td>
              <td>{new Date(log.createdAt).toLocaleString()}</td>
            </tr>
          ))}
        </tbody>
      </table>
      <p>
        Page {page} of {totalPages} ({totalDocs} total)
      </p>
    </div>
  );
}

useUsageLogs parameters:

| Parameter | Type | Required | Description | | ---------------- | ----------------------------- | -------- | ----------------------------------------------- | | workspaceId | string \| null \| undefined | Yes | Workspace ID (null/undefined disables fetching) | | quotaSlug | string | No | Filter logs by quota slug | | options.from | string | No | ISO date string — filter logs from this date | | options.to | string | No | ISO date string — filter logs until this date | | options.source | string | No | Filter logs by source | | options.page | number | No | Page number (default: 1) | | options.limit | number | No | Results per page (default: 20) |

Client-Side Hooks Summary

| Hook | Purpose | | ------------------------------------------------- | ------------------------------------------ | | useRecordUsage(workspaceId) | Record quota consumption (mutation) | | useQuotaUsageStatus(workspaceId, quotaSlug) | Get single quota status (auto-fetches) | | useAllQuotaUsage(workspaceId) | Get all quotas status (auto-fetches) | | useUsageLogs(workspaceId, quotaSlug?, options?) | Get paginated usage history (auto-fetches) |

Server-Side (REST API)

For backend services, background jobs, or API routes — call the BuildBase API directly. This is the recommended approach when usage happens on your server (e.g., processing an API request, running a cron job, handling webhooks).

Step 1: Get a Session ID

Exchange your org API token for a session ID. You can do this once and reuse the session for multiple requests (default expiry: 30 days).

// Do this once at startup or cache the result
const TOKEN = 'your-org-id:your-api-secret'; // from BuildBase dashboard

async function getSessionId(): Promise<string> {
  const response = await fetch('https://your-server.buildbase.app/api/v1/public/token/exchange', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      token: TOKEN,
      expiresIn: 2592000, // 30 days (optional, default is 30 days)
    }),
  });
  const data = await response.json();
  return data.sessionId;
}

Step 2: Record Usage

const SESSION_ID = await getSessionId();
const BASE_URL = 'https://your-server.buildbase.app/api/v1/public';

async function recordUsage(workspaceId: string, quotaSlug: string, quantity: number) {
  const response = await fetch(`${BASE_URL}/workspaces/${workspaceId}/subscription/usage`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-session-id': SESSION_ID,
    },
    body: JSON.stringify({
      quotaSlug,
      quantity,
      source: 'backend', // optional: helps distinguish from client-side usage
      metadata: {}, // optional: attach custom data
      idempotencyKey: undefined, // optional: prevent duplicate recordings
    }),
  });
  return response.json();
}

// Example: Record usage in an Express route handler
app.post('/api/generate-report', async (req, res) => {
  const { workspaceId } = req.user; // your auth

  // Record quota usage BEFORE or AFTER doing the work
  const usage = await recordUsage(workspaceId, 'reports', 1);

  if (usage.available <= 0 && !usage.hasOverage) {
    return res.status(429).json({ error: 'Report quota exceeded' });
  }

  // ... generate the report ...
  res.json({ success: true, quotaRemaining: usage.available });
});

Step 3: Check Usage Status (Optional)

// Get status for a single quota
async function getQuotaStatus(workspaceId: string, quotaSlug: string) {
  const response = await fetch(
    `${BASE_URL}/workspaces/${workspaceId}/subscription/usage/status?quotaSlug=${quotaSlug}`,
    { headers: { 'x-session-id': SESSION_ID } }
  );
  return response.json();
  // Returns: { quotaSlug, consumed, included, available, overage, hasOverage }
}

// Get status for ALL quotas
async function getAllQuotaStatus(workspaceId: string) {
  const response = await fetch(`${BASE_URL}/workspaces/${workspaceId}/subscription/usage/all`, {
    headers: { 'x-session-id': SESSION_ID },
  });
  return response.json();
  // Returns: { quotas: { [slug]: { consumed, included, available, overage, hasOverage } } }
}

// Example: Check before allowing an action
app.post('/api/send-email', async (req, res) => {
  const status = await getQuotaStatus(req.user.workspaceId, 'emails');

  if (status.available <= 0) {
    return res.status(429).json({
      error: 'Email quota exceeded',
      consumed: status.consumed,
      included: status.included,
    });
  }

  await recordUsage(req.user.workspaceId, 'emails', 1);
  // ... send the email ...
});

Batch Usage Recording (High-Volume)

For bulk operations (batch exports, cron jobs, webhooks) that process hundreds or thousands of items, use the batch endpoint to record all usage in a single request instead of calling the API per-item.

// Using BuildBase SDK (recommended)
import { BuildBase } from '@buildbase/sdk';

const bb = BuildBase({ serverUrl: BASE_URL, version: 'v1', orgId: ORG_ID, token: TOKEN });

await bb.usage.recordBatch(workspaceId, {
  items: [
    { quotaSlug: 'images', quantity: 500, source: 'batch-export-job' },
    { quotaSlug: 'videos', quantity: 10, source: 'batch-export-job' },
    { quotaSlug: 'images', quantity: 200, metadata: { jobId: 'abc123' } },
  ],
});
// Returns: { success, total: 3, succeeded: 3, failed: 0, results: [...] }

// Using REST API directly
const response = await fetch(`${BASE_URL}/workspaces/${workspaceId}/subscription/usage/batch`, {
  method: 'POST',
  headers: { 'x-session-id': SESSION_ID, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    items: [
      { quotaSlug: 'images', quantity: 500, source: 'batch-export' },
      { quotaSlug: 'videos', quantity: 10 },
    ],
  }),
});

• Max 100 items per request
• Each item is processed independently — a single failure doesn't fail the batch
• Supports metadata, source, and idempotencyKey per item
• Returns per-item results with success or error for each

Server-Side API Reference

| Endpoint | Method | Description | | --------------------------------------------------------------------- | ------ | --------------------------------- | | /api/v1/public/token/exchange | POST | Exchange API token for session ID | | /api/v1/public/workspaces/:id/subscription/usage | POST | Record quota usage | | /api/v1/public/workspaces/:id/subscription/usage/status?quotaSlug=X | GET | Get single quota status | | /api/v1/public/workspaces/:id/subscription/usage/all | GET | Get all quotas status | | /api/v1/public/workspaces/:id/subscription/usage/logs | GET | Get paginated usage logs |

All endpoints (except /token/exchange) require the x-session-id header.

Record usage request body:

| Field | Type | Required | Description | | ---------------- | -------- | -------- | -------------------------------------------------------------- | | quotaSlug | string | Yes | Quota identifier (e.g. 'api_calls', 'emails', 'storage') | | quantity | number | Yes | Units to consume (minimum 1) | | metadata | object | No | Custom metadata to attach to the usage record | | source | string | No | Source identifier (e.g. 'backend', 'worker', 'cron') | | idempotencyKey | string | No | Unique key for deduplication |

Record usage response:

| Field | Type | Description | | ------------- | --------- | -------------------------------------------- | | used | number | Quantity recorded in this request | | consumed | number | Total usage in the current billing period | | included | number | Total units included in the plan | | available | number | Remaining units before overage | | overage | number | Units used beyond the included amount | | billedAsync | boolean | Whether overage billing was queued to Stripe |

🚦 Quota Gates

Control UI visibility based on quota usage status. Quota data is loaded once per workspace via QuotaUsageContextProvider (included in SaaSOSProvider by default) and refetched automatically after recording usage.

Gate Components

import {
  WhenQuotaAvailable,
  WhenQuotaExhausted,
  WhenQuotaOverage,
  WhenQuotaThreshold,
} from '@buildbase/sdk/react';

function Dashboard() {
  return (
    <div>
      {/* Show action button only when quota has remaining units */}
      <WhenQuotaAvailable slug="api_calls">
        <MakeApiCallButton />
      </WhenQuotaAvailable>

      {/* Show upgrade prompt when quota is fully consumed */}
      <WhenQuotaExhausted slug="api_calls">
        <UpgradePrompt message="You've used all your API calls this month." />
      </WhenQuotaExhausted>

      {/* Show warning when usage exceeds included amount (overage billing active) */}
      <WhenQuotaOverage slug="api_calls">
        <OverageBillingWarning />
      </WhenQuotaOverage>

      {/* Show warning when usage reaches 80% of included amount */}
      <WhenQuotaThreshold slug="api_calls" threshold={80}>
        <p>Warning: You've used over 80% of your API calls.</p>
      </WhenQuotaThreshold>
    </div>
  );
}

With Loading and Fallback

All quota gate components support optional loadingComponent and fallbackComponent props:

<WhenQuotaAvailable
  slug="emails"
  loadingComponent={<Skeleton className="h-10" />}
  fallbackComponent={<p>Email quota exhausted. <a href="/upgrade">Upgrade now</a></p>}
>
  <SendEmailButton />
</WhenQuotaAvailable>

<WhenQuotaThreshold
  slug="storage"
  threshold={90}
  loadingComponent={<Spinner />}
  fallbackComponent={null}
>
  <StorageWarningBanner />
</WhenQuotaThreshold>

Quota Gate Components Reference

| Component | Renders children when | Props | | -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------- | | WhenQuotaAvailable | Quota has remaining units (available > 0) | slug, children, loadingComponent?, fallbackComponent? | | WhenQuotaExhausted | Quota is fully consumed (available <= 0) | slug, children, loadingComponent?, fallbackComponent? | | WhenQuotaOverage | Usage exceeds included amount (hasOverage) | slug, children, loadingComponent?, fallbackComponent? | | WhenQuotaThreshold | Usage percentage >= threshold | slug, threshold (0-100), children, loadingComponent?, fallbackComponent? |

All gates must be used inside QuotaUsageContextProvider (included in SaaSOSProvider). By default they return null while loading or when the condition is not met.

useQuotaUsageContext

Use the hook when you need raw quota data or a manual refetch (e.g. after a bulk operation):

import { useQuotaUsageContext } from '@buildbase/sdk/react';

function QuotaDebug() {
  const { quotas, loading, refetch } = useQuotaUsageContext();

  if (loading) return <Spinner />;
  if (!quotas) return <p>No quota data</p>;

  return (
    <div>
      {Object.entries(quotas).map(([slug, usage]) => (
        <p key={slug}>
          {slug}: {usage.consumed}/{usage.included}
        </p>
      ))}
      <button onClick={() => refetch()}>