Check Endpoint

Verify customer access to features and check remaining balances in real-time

Overview

The /check endpoint verifies whether a customer has access to a specific feature or product. Use it to:

• Gate features behind paywalls
• Display remaining usage limits
• Show upgrade prompts when limits are reached
• Combine check + track in a single atomic operation

Quick Start

React Frontend

import { useCustomer } from '@useautumn/autumn-js/react';

function FeatureButton() {
  const { check } = useCustomer();

  const handleClick = () => {
    const result = check({ featureId: "ai_tokens" });
    
    if (!result.allowed) {
      alert(`AI limit reached. ${result.balance?.remaining || 0} tokens left.`);
      return;
    }
    
    // Proceed with feature
    generateAIContent();
  };

  return <button onClick={handleClick}>Generate AI Content</button>;
}

import { Autumn } from '@useautumn/sdk';

const autumn = new Autumn({ 
  secretKey: process.env.AUTUMN_SECRET_KEY 
});

const result = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "ai_tokens",
  requiredBalance: 100  // Need 100 tokens
});

if (!result.allowed) {
  return res.status(403).json({ 
    error: "Insufficient AI tokens",
    remaining: result.balance?.remaining 
  });
}

// Process the AI request
await generateAIContent();

from autumn import Autumn

autumn = Autumn(secret_key=os.environ["AUTUMN_SECRET_KEY"])

result = autumn.balances.check(
    customer_id="cus_123",
    feature_id="ai_tokens",
    required_balance=100
)

if not result.allowed:
    return {"error": "Insufficient AI tokens"}, 403

# Process the AI request
generate_ai_content()

Parameters

customerId · string · required

The ID of the customer to check access for.

featureId · string

The ID of the feature to check. Use either featureId or productId.

productId · string

The ID of the product to check. Use either featureId or productId.

entityId · string

The ID of the entity for entity-scoped checks (e.g., per-seat limits).

requiredBalance · number · default: "1"

Minimum balance required for access. Returns allowed: false if the customer’s balance is below this value.

// Check if customer has at least 500 tokens
check({ featureId: "api_calls", requiredBalance: 500 })

sendEvent · boolean · default: "false"

If true, atomically records a usage event while checking access. Combines check + track in one call.

// Check AND consume 100 tokens in one atomic operation
check({ 
  featureId: "ai_tokens", 
  requiredBalance: 100,
  sendEvent: true  // Deducts 100 tokens if allowed
})

withPreview · boolean · default: "false"

If true, includes upgrade/upsell information when access is denied. Useful for displaying paywalls.

const result = check({ 
  featureId: "advanced_analytics", 
  withPreview: true 
});

if (!result.allowed && result.preview) {
  // Show upgrade modal with result.preview.products
}

properties · object

Additional properties to attach to the usage event (only used if sendEvent: true).

Response

interface CheckResponse {
  allowed: boolean;              // Whether customer has access
  customerId: string;            // The customer ID
  entityId?: string;             // The entity ID (if entity-scoped)
  requiredBalance?: number;      // The required balance checked
  balance: Balance | null;       // Customer's balance details
  preview?: {                    // Upgrade info (if withPreview: true and !allowed)
    scenario: "usage_limit" | "feature_flag";
    title: string;
    message: string;
    featureId: string;
    featureName: string;
    products: Product[];         // Products that grant access
  };
}

interface Balance {
  featureId: string;
  granted: number;               // Total balance granted
  remaining: number;             // Balance remaining
  usage: number;                 // Current usage
  unlimited: boolean;            // Whether feature is unlimited
  overageAllowed: boolean;       // Whether overage is allowed
  nextResetAt: number | null;    // Timestamp of next reset
  breakdown?: BalanceBreakdown[];  // Detailed balance sources
}

Common Use Cases

Simple Feature Gate

React

function ExportButton() {
  const { check } = useCustomer();
  
  const handleExport = () => {
    const { allowed } = check({ featureId: "pdf_export" });
    
    if (!allowed) {
      showUpgradeModal();
      return;
    }
    
    exportToPDF();
  };
  
  return <button onClick={handleExport}>Export to PDF</button>;
}

app.post('/export', async (req, res) => {
  const { allowed } = await autumn.balances.check({
    customerId: req.user.id,
    featureId: "pdf_export"
  });
  
  if (!allowed) {
    return res.status(403).json({ error: "Upgrade required" });
  }
  
  const pdf = await generatePDF(req.body);
  res.send(pdf);
});

Display Remaining Usage

React

function UsageMeter() {
  const { check } = useCustomer();
  const result = check({ featureId: "api_calls" });
  
  if (!result.balance) return null;
  
  const { remaining, granted, unlimited } = result.balance;
  
  if (unlimited) {
    return <div>Unlimited API calls</div>;
  }
  
  return (
    <div>
      {remaining} / {granted} API calls remaining
      {remaining < granted * 0.1 && (
        <button onClick={() => upgradePlan()}>Upgrade for more</button>
      )}
    </div>
  );
}

app.get('/usage', async (req, res) => {
  const result = await autumn.balances.check({
    customerId: req.user.id,
    featureId: "api_calls"
  });
  
  res.json({
    remaining: result.balance?.remaining || 0,
    total: result.balance?.granted || 0,
    unlimited: result.balance?.unlimited || false
  });
});

Atomic Check + Track

Use sendEvent: true to check access and record usage in a single atomic operation:

Backend

// Check if customer has 1000 tokens AND consume them atomically
const result = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "ai_tokens",
  requiredBalance: 1000,
  sendEvent: true,  // Atomically deduct tokens if allowed
  properties: {
    model: "gpt-4",
    requestId: "req_xyz"
  }
});

if (!result.allowed) {
  return res.status(403).json({ error: "Insufficient tokens" });
}

// Tokens already deducted, proceed with AI generation
await generateAI();

# Check and consume in one atomic operation
result = autumn.balances.check(
    customer_id="cus_123",
    feature_id="ai_tokens",
    required_balance=1000,
    send_event=True,  # Atomically deduct if allowed
    properties={"model": "gpt-4"}
)

if not result.allowed:
    return {"error": "Insufficient tokens"}, 403

# Proceed with generation
generate_ai()

Show Upgrade Options on Limit

React

function AnalyticsPage() {
  const { check } = useCustomer();
  const result = check({ 
    featureId: "advanced_analytics",
    withPreview: true 
  });
  
  if (!result.allowed && result.preview) {
    return (
      <UpgradePrompt
        title={result.preview.title}
        message={result.preview.message}
        plans={result.preview.products}
      />
    );
  }
  
  return <AdvancedAnalyticsDashboard />;
}

const result = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "advanced_analytics",
  withPreview: true
});

if (!result.allowed && result.preview) {
  return res.status(403).json({
    error: result.preview.message,
    upgradeOptions: result.preview.products
  });
}

Entity-Scoped Checks (Per-Seat Limits)

Backend

// Check if a specific workspace has access
const result = await autumn.balances.check({
  customerId: "cus_123",
  entityId: "workspace_abc",  // Check specific workspace
  featureId: "team_members",
  requiredBalance: 1  // Check if they can add 1 more member
});

if (!result.allowed) {
  return res.status(403).json({ 
    error: "Team member limit reached for this workspace" 
  });
}

await addTeamMember(workspaceId, newMemberId);

Error Handling

React

import { AutumnClientError } from '@useautumn/autumn-js/react';

try {
  const result = check({ featureId: "api_calls" });
  
  if (!result.allowed) {
    console.log("Access denied", result.balance?.remaining);
  }
} catch (error) {
  // Note: check() in React is local and doesn't throw
  // It uses cached customer data from useCustomer()
}

try {
  const result = await autumn.balances.check({
    customerId: "cus_123",
    featureId: "api_calls"
  });
} catch (error) {
  if (error.code === "customer_not_found") {
    // Customer doesn't exist
  } else if (error.code === "feature_not_found") {
    // Feature doesn't exist
  }
}

Balance Breakdown

When a customer has multiple sources of balance (multiple plans, top-ups, rollovers), the breakdown array shows where each portion comes from:

const result = await autumn.balances.check({
  customerId: "cus_123",
  featureId: "api_calls"
});

result.balance?.breakdown?.forEach(item => {
  console.log(`Plan ${item.planId}: ${item.remaining} of ${item.includedGrant} remaining`);
  if (item.reset) {
    console.log(`Resets at: ${new Date(item.reset.resetsAt)}`);
  }
});

Query Parameters

skipCache · boolean · default: "false"

Bypass cache and fetch fresh data from the database.

expand · string[]

Expand related objects. Supports: "balance.feature"

// Include full feature object in response
await autumn.balances.check(
  { customerId: "cus_123", featureId: "api_calls" },
  { expand: ["balance.feature"] }
);

Related Endpoints

• Track Endpoint - Record usage events after check
• Attach Endpoint - Upgrade customer when limits are reached
• Webhooks - Listen for balance changes

Next Steps

Track Usage

Learn how to record usage events

Handle Upgrades

Upgrade customers when they hit limits