PHP SDK

composer require crovver/crovver-php

use Crovver\CrovverClient;
use Crovver\CrovverConfig;

$client = new CrovverClient(new CrovverConfig(
    apiKey: getenv('CROVVER_SECRET_KEY'),
));

use Crovver\Types\CreateTenantRequest;

// Create a tenant (B2B: workspace or user)
$tenant = $client->createTenant(new CreateTenantRequest(
    externalTenantId: 'workspace_abc123',
    name: 'Acme Corp',
    externalUserId: 'user_123',
));

// Retrieve a tenant
$tenant = $client->getTenant('workspace_abc123');

$plans = $client->getPlans();

foreach ($plans->plans as $plan) {
    echo $plan->name . ' - $' . ($plan->priceAmount / 100) . '/mo';
}

$result = $client->getSubscriptions('workspace_abc123');

foreach ($result->subscriptions as $sub) {
    echo $sub->status; // active, trial, past_due, pending_cancel, canceled, expired
}

// Single-product org
$canAccess = $client->canAccess('workspace_abc123', 'advanced_analytics');

// Multi-product: scope to a specific product
$canAccess = $client->canAccess('workspace_abc123', 'advanced_analytics', 'product-a');

// Subscription-existence check — does this tenant have any active sub for product-a?
$hasProduct = $client->canAccess('workspace_abc123', '', 'product-a');

$balance = $client->getCreditsBalance('workspace_abc123');

foreach ($balance['pools'] as $pool) {
    echo $pool['poolKey'] . ': ' . $pool['remaining'] . ' remaining';
}

$result = $client->consumeCredits(
    tenantId: 'workspace_abc123',
    poolKey: 'ai_generations',
    amount: 1,
    idempotencyKey: bin2hex(random_bytes(16)), // stable per user action
    metadata: ['prompt' => 'summarise report'], // optional
);

if ($result->result === 'success') {
    echo 'Remaining: ' . $result->remaining;
} else {
    // result === 'insufficient_credits'
    // Prompt the user to purchase an add-on or upgrade
}

$addons = $client->listAvailableAddons('workspace_abc123');

foreach ($addons as $addon) {
    echo $addon['name'] . ': ' . $addon['creditQty'] . ' credits — '
        . $addon['currency'] . ' ' . $addon['amount'];
}

$purchase = $client->purchaseAddon(
    externalTenantId: 'workspace_abc123',
    addonId: 'addon_uuid',
    currency: 'USD',
    idempotencyKey: bin2hex(random_bytes(16)),
    successUrl: 'https://yourapp.com/billing/success',
    cancelUrl: 'https://yourapp.com/billing/cancel',
);

if ($purchase->requiresPayment) {
    // Redirect to Stripe checkout
    header('Location: ' . $purchase->checkoutUrl);
    exit;
} else {
    // Credits added immediately (free add-on or already processed)
    echo $purchase->creditQty . ' credits added';
}

$active = $client->getActiveAddonCredits('workspace_abc123');

foreach ($active as $pool) {
    echo $pool['poolKey'] . ': ' . $pool['remaining'] . ' remaining';
}

// ❌ Deprecated — use consumeCredits() instead
$client->recordUsage('workspace_abc123', 'api_calls', 1);

// ❌ Deprecated — use getCreditsBalance() instead
$limit = $client->checkUsageLimit('workspace_abc123', 'api_calls');
echo $limit->current . ' / ' . $limit->limit;

use Crovver\Types\CreateCheckoutSessionRequest;

$session = $client->createCheckoutSession(new CreateCheckoutSessionRequest(
    externalTenantId: 'workspace_abc123',
    planId: 'plan_pro',
    currency: 'USD',                                    // optional; defaults to plan's first price
    successUrl: 'https://yourapp.com/billing/success',
    cancelUrl: 'https://yourapp.com/billing/cancel',
));

// Redirect user to $session->checkoutUrl

$count = $client->getSeatCount('workspace_abc123');

echo $count->activeCount;           // Active allocated seats
echo $count->capacityUnits;         // Total seats in subscription
echo $count->utilizationPercentage; // activeCount / capacityUnits × 100
echo $count->billingMode;           // recurring | manual | free
echo $count->exceeded ? 'Over limit' : 'Within limit';

use Crovver\Types\AllocateSeatRequest;

$result = $client->allocateSeat(new AllocateSeatRequest(
    requestingEntityId: 'workspace_abc123',
    externalUserId: 'user_456',
    email: 'alice@acme.com',
    name: 'Alice',
));

if ($result->success) {
    echo 'Seat allocated. Active seats: ' . $result->capacity->activeCount;
}

$result = $client->allocateSeat(new AllocateSeatRequest(
    requestingEntityId: 'workspace_abc123',
    externalUserId: 'user_789',
));

if ($result->requiresProration) {
    // Show the user the upgrade cost before proceeding
    echo 'Adding this seat costs ' . $result->proration->amount . ' ' . $result->proration->currency;
    echo ' for ' . $result->proration->daysRemaining . ' remaining days in the billing period.';

    // Then call createProrationCheckout to start payment
    $checkout = $client->createProrationCheckout(
        externalTenantId: 'workspace_abc123',
        newCapacity: $result->proration->newSeats,
        successUrl: 'https://yourapp.com/seats?upgraded=1',
        cancelUrl: 'https://yourapp.com/seats',
    );

    // Redirect to $checkout->checkoutUrl
}

use Crovver\Types\BulkAllocateSeatsRequest;
use Crovver\Types\BulkAllocateSeatUser;

$result = $client->bulkAllocateSeats(new BulkAllocateSeatsRequest(
    requestingEntityId: 'workspace_abc123',
    users: [
        new BulkAllocateSeatUser('user_1', 'alice@acme.com', 'Alice'),
        new BulkAllocateSeatUser('user_2', 'bob@acme.com',   'Bob'),
        new BulkAllocateSeatUser('user_3', 'carol@acme.com', 'Carol'),
    ],
    metadata: ['addedBy' => 'admin_789'], // optional
));

echo count($result->allocated) . ' allocated';
echo count($result->skipped)   . ' skipped (already active)';
echo count($result->rejected)  . ' rejected (over capacity)';

echo $result->capacity->activeCount . ' / ' . $result->capacity->capacityUnits . ' seats';

if (count($result->rejected) > 0) {
    // Call createProrationCheckout to upgrade capacity, then retry $result->rejected
    echo $result->message;
}

// Active users, first page (defaults)
$result = $client->getAllocations('workspace_abc123');

foreach ($result->allocations as $user) {
    echo $user->externalUserId . ' — ' . $user->email . ' (' . $user->status . ')';
    echo ' since ' . $user->allocatedAt;
}

// Capacity summary
echo $result->capacity->activeCount . ' / ' . $result->capacity->capacityUnits . ' seats';
echo $result->capacity->utilizationPercentage . '% utilized';

if ($result->capacity->exceeded) {
    // Prompt upgrade
}

// Pagination
echo $result->pagination->total . ' total — page '
    . $result->pagination->page . ' of ' . $result->pagination->totalPages;

// Page through all users including removed
$page2 = $client->getAllocations(
    requestingEntityId: 'workspace_abc123',
    status: 'all',    // 'active' | 'removed' | 'all'
    page: 2,
    limit: 25,        // max 100, default 50
);

$checkout = $client->createProrationCheckout(
    externalTenantId: 'workspace_abc123',
    newCapacity: 25,
    successUrl: 'https://yourapp.com/seats?upgraded=1',
    cancelUrl: 'https://yourapp.com/seats',
);

if ($checkout->requiresPayment) {
    // Redirect to the provider's checkout page
    header('Location: ' . $checkout->checkoutUrl);
} else {
    // Seat count was updated without payment (e.g. within free allowance)
    echo $checkout->message;
}

use Crovver\CrovverError;

try {
    $result = $client->getSubscriptions('workspace_abc123');
} catch (CrovverError $e) {
    $e->getMessage();     // Human-readable message
    $e->getStatusCode();  // HTTP status code (null for network errors)
    $e->getErrorCode();   // API error code string
    $e->isRetryable();    // Whether the SDK already retried
}