Customers

Understanding customer management, entities, and customer products in Autumn

Overview

Customers are the end-users or organizations that subscribe to your products. In Autumn, customers are the central entity that connects to products, tracks usage, and manages billing.

Customer Structure

type Customer = {
  internal_id: string;           // Internal database identifier
  id: string | null;             // Your application's customer ID
  org_id: string;                // Your organization ID
  
  // Identity
  name: string | null;
  email: string | null;
  fingerprint: string | null;    // Anonymous user tracking
  
  // Environment
  env: "test" | "prod";
  
  // Payment processor
  processor: {
    type: "stripe";
    id: string;                  // Stripe customer ID
  } | null;
  
  // Configuration
  metadata: Record<string, unknown>;
  send_email_receipts: boolean;
  
  created_at: number;
};

Customer Identity

Autumn provides flexible customer identification:

1. Identified Customers

Customers with a known id from your application:

const { attach } = useAutumn();

// Attach product to a specific customer
await attach({
  customerId: "user_123",
  productId: "pro"
});

2. Anonymous Customers

Users tracked by fingerprint before signing up:

{
  id: null,
  email: "[e-mail]",
  fingerprint: "fp_abc123",  // Browser/device fingerprint
}

When an anonymous customer signs up, you can update their record to include an id, preserving their usage history and subscriptions.

3. Email-only Customers

Customers identified by email:

{
  id: null,
  email: "[e-mail]",
  fingerprint: null,
}

Full Customer Object

When querying customers through the API, you’ll often work with FullCustomer:

type FullCustomer = Customer & {
  customer_products: FullCusProduct[];     // Active subscriptions
  entities: Entity[];                      // Multi-entity support
};

Example:

const customer: FullCustomer = {
  id: "user_123",
  email: "[e-mail]",
  name: "Alice Johnson",
  // ... other customer fields
  
  customer_products: [
    {
      product_id: "pro",
      status: "active",
      starts_at: 1704067200000,
      // ... subscription details
    }
  ],
  
  entities: [
    {
      id: "acme_workspace_1",
      type: "workspace",
      // ... entity details
    }
  ]
};

Customer Products

When a customer subscribes to a product, a CustomerProduct record is created:

type CustomerProduct = {
  id: string;
  internal_customer_id: string;
  internal_product_id: string;
  product_id: string;            // User-facing product ID
  
  // Status tracking
  status: string;                // "active", "trialing", "past_due", etc.
  canceled: boolean;
  canceled_at: number | null;
  
  // Timing
  created_at: number;
  starts_at: number | null;      // When product becomes active
  ended_at: number | null;       // When product ended
  trial_ends_at: number | null;  // Free trial expiration
  
  // Free trial
  free_trial_id: string | null;
  
  // Configuration
  options: any[];                // Feature-specific options (e.g., quantity)
  quantity: number;              // For seat-based pricing
  collection_method: string;     // "charge_automatically" or "send_invoice"
  
  // Payment processor
  processor: {
    type: "stripe" | "revenuecat";
    id: string;                  // Subscription ID in processor
  } | null;
  
  subscription_ids: string[];    // Stripe subscription IDs
  scheduled_ids: string[];       // Scheduled changes
  
  // Metadata
  is_custom: boolean;            // Custom pricing for this customer
  api_version: number;
  external_id: string | null;    // Your external reference
};

Customer Product Lifecycle

A customer product goes through several states:

Common statuses:

• trialing - In free trial period
• active - Active subscription with valid payment
• past_due - Payment failed, retrying
• canceled - Canceled but still active until period ends
• ended - Subscription fully terminated

Checking Customer Access

Use the /check endpoint to verify what a customer can access:

const { check } = useAutumn();

// Check if customer has access to a product
const { data } = await check({ 
  customerId: "user_123",
  productId: "pro" 
});

if (data.allowed) {
  // Customer has active Pro subscription
}

See Features for checking feature-level access.

Entities

Entities enable multi-tenancy within a single customer account. This is useful for:

• Workspaces in team collaboration tools
• Projects in development platforms
• Organizations in B2B SaaS
• Stores in e-commerce platforms

type Entity = {
  internal_id: string;
  id: string;                    // Your entity identifier
  internal_customer_id: string;  // Parent customer
  
  type: string | null;           // "workspace", "project", etc.
  metadata: Record<string, unknown>;
  
  created_at: number;
};

Using Entities

Attach products to specific entities:

const { attach } = useAutumn();

// Attach product to a specific workspace
await attach({
  customerId: "user_123",
  entityId: "workspace_abc",
  productId: "team"
});

Track usage per entity:

const { track } = useAutumn();

await track({
  customerId: "user_123",
  entityId: "workspace_abc",
  featureId: "api_calls",
  value: 100
});

Each entity can have its own products and usage tracking, allowing you to bill different teams or projects separately within the same customer account.

Customer Options

When attaching products, you can specify feature-specific options:

type FeatureOptions = {
  feature_id: string;
  internal_feature_id: string;
  quantity: number;              // e.g., number of seats purchased
};

Example with seat-based pricing:

await attach({
  customerId: "user_123",
  productId: "team",
  options: [
    {
      feature_id: "seats",
      quantity: 5               // Purchase 5 seats
    }
  ]
});

Customer Metadata

Store arbitrary data on customer records:

{
  id: "user_123",
  email: "[e-mail]",
  metadata: {
    company: "Acme Corp",
    industry: "Technology",
    signup_source: "google_ads",
    account_manager: "[e-mail]"
  }
}

Metadata is:

• Stored as JSON
• Synced to Stripe (if using Stripe)
• Queryable through the API
• Useful for segmentation and analytics

Customer Creation

Customers are created automatically when you call /attach or /track with a new customer ID:

// First call creates the customer
await attach({
  customerId: "user_789",     // New customer
  productId: "pro"
});

You can also create customers explicitly through the API or dashboard.

Stripe Integration

When Stripe is connected, Autumn automatically:

1. Creates Stripe customers when attaching products
2. Syncs customer data (name, email, metadata) to Stripe
3. Manages payment methods through Stripe
4. Handles webhooks for subscription events

{
  id: "user_123",
  email: "[e-mail]",
  processor: {
    type: "stripe",
    id: "cus_abc123"           // Stripe customer ID
  }
}

Autumn handles all the complexity of syncing customer state between your app and Stripe, so you never have to write webhook handlers.

Customer Queries

Common customer operations:

// Get customer with all products
const customer = await getFullCustomer({ 
  customerId: "user_123" 
});

// Check active subscriptions
const activeProducts = customer.customer_products.filter(
  cp => cp.status === "active" && !cp.canceled
);

// Find customer by email
const customer = await findCustomerByEmail({
  email: "[e-mail]",
  env: "prod"
});

Next Steps

• Learn about Products and Plans to understand what customers subscribe to
• Explore Features to control what customers can access
• Read about Billing Lifecycle to understand subscription states