Credits Allocation

Overview

The Credits Allocation system governs how MLC (Meclabs Credits) are distributed, managed, and accessed across the MECLABS AI platform. This hierarchical allocation model supports multiple business scenarios: subscription tiers with pooled credits, re-sellable Customer Kits with bundled credits, and flexible top-up purchases for on-demand usage.

Allocation Hierarchy

Organization-Level Pool

Each subscription tier includes a monthly allocation of pooled credits shared across all Organization Members:

• Build Tier: 6,000 MLC pooled credits
• Sell Tier: 18,000 MLC pooled credits
• Scale Tier: 75,000 MLC pooled credits

These credits refresh monthly on billing cycle renewal and are accessible to all internal team members.

Customer Kit Credits

Customer Kits operate independently from organization pools:

• Per-Kit Allocation: 1,000 MLC bundled with each $20/month kit
• Isolation: Kit credits are segregated from organization pools
• Activation: Credits become available immediately upon kit deployment
• Target Users: External customers accessing your Agent Delivery System (ADS)

Top-Up Credits

Organizations can purchase additional credits on-demand:

• Pricing: $0.0135 per MLC (35% markup over base compute cost)
• Pool Integration: Top-ups merge with existing organization pool
• No Minimum: Purchase any amount based on projected needs
• Immediate Availability: Credits activate upon payment confirmation

Allocation Rules

Monthly Refresh Cycle

Billing Cycle

Credits refresh on the monthly anniversary of subscription activation, not calendar months.

1. Automatic Replenishment: Pooled credits reset to tier allocation on billing date
2. No Rollover: Unused credits do not carry forward (90-day expiration applies)
3. Proration: New subscriptions receive full allocation regardless of join date
4. Downgrades: Credit reduction applies at next billing cycle

21-Day Build Access Pass

Special allocation rules apply during the initial build phase:

• Funded Builds: $10,000 credit allocation for voucher recipients
• Trial Environment: Credits operate within MECLABS sandbox
• Acceptance Trigger: Day 21 decision converts to subscription allocation
• Decline Consequence: Access terminates, no credit transfer

Credit Priority Order

When multiple credit sources exist, consumption follows this hierarchy:

1. Promotional Credits (if applicable)
2. Subscription Pool Credits (monthly allocation)
3. Top-Up Credits (purchased on-demand)
4. Overage Billing (automatic at $0.0135/MLC)

Distribution Mechanisms

Organization Members

Internal team seats draw from the shared organization pool:

interface OrgMemberAccess {
  poolType: "organization";
  creditSource: "subscription" | "topup";
  sharedPool: true;
  individualLimit?: number; // Optional per-user caps
}

Customer Kit Assignment

Each Customer Kit creates an isolated credit environment:

interface CustomerKitAllocation {
  kitId: string;
  credits: 1000; // Fixed monthly allocation
  isolation: "complete"; // No cross-kit access
  ownership: "reseller" | "direct";
}

Team-Level Sub-Pools

Scale tier organizations can create team-specific allocations:

interface TeamAllocation {
  teamId: string;
  parentOrgId: string;
  creditBudget?: number; // Optional team limit
  members: string[]; // User IDs with access
}

Automated Provisioning

Subscription Activation Flow

1. Payment Confirmation: Stripe webhook triggers allocation
2. Credit Pool Creation: Organization receives tier-specific credits
3. Seat Provisioning: Included Org Members activated
4. Kit Bundling: Sell/Scale tiers receive included Customer Kits
5. Dashboard Update: Real-time balance reflection

Customer Kit Deployment

1. Purchase/Assignment: Kit allocated from included bundle or purchased
2. Unique Login Creation: Isolated user account generated
3. Credit Activation: 1,000 MLC immediately available
4. ADS Access: Kit user can interact with deployed agents
5. Usage Tracking: Consumption tracked separately from org pool

Top-Up Processing

1. Purchase Initiation: User requests additional credits
2. Payment Processing: Stripe handles transaction
3. Instant Allocation: Credits merge with organization pool
4. Notification: Admin receives confirmation and updated balance
5. Audit Trail: Transaction logged for reporting

Allocation Tracking

Real-Time Balance Monitoring

Organizations access credit information through multiple interfaces:

• Dashboard Widget: Current balance and burn rate
• API Endpoint: Programmatic balance queries
• Email Alerts: Threshold notifications (50%, 75%, 90% consumed)
• Usage Reports: Historical allocation and consumption data

Attribution Granularity

Credit consumption tracks at multiple levels:

interface CreditAttribution {
  organizationId: string;
  teamId?: string;
  userId: string;
  widgetId?: string;
  timestamp: Date;
  mlcConsumed: number;
  model: string;
  provider: string;
}

Upgrade Triggers

Allocation-Based Upgrades

The system prompts tier upgrades when allocation limits approach:

Current Tier	Trigger Condition	Recommended Action
Build	>5,000 MLC monthly usage	Upgrade to Sell (18,000 MLC)
Sell	>15,000 MLC monthly usage	Upgrade to Scale (75,000 MLC)
Scale	>70,000 MLC monthly usage	Purchase top-ups or negotiate enterprise

Kit Allocation Exhaustion

When included Customer Kits are fully deployed:

• Build → Sell: Gain 10 included kits
• Sell → Scale: Expand to 45 included kits
• Alternative: Purchase additional kits at $20/month

Billing Integration

Stripe Automation

Credit allocation integrates with Stripe for seamless provisioning:

1. Subscription Management: Tier changes trigger reallocation
2. Usage-Based Billing: Overage charges at $0.0135/MLC
3. Invoice Generation: Monthly statements include allocation details
4. Payment Methods: Credit card, ACH, wire (enterprise)

Proration Handling

Mid-cycle changes follow these allocation rules:

• Upgrades: Immediate access to higher allocation
• Downgrades: Reduced allocation at next billing cycle
• Cancellations: Credits remain until period end
• Reactivations: Fresh allocation upon payment

Partner Program Allocations

Reseller Credit Management

Certified Partners receive special allocation privileges:

1. Wholesale Kits: Purchase at $20, resell at market rate
2. Volume Discounts: Negotiable for 100+ kit commitments
3. White-Label Options: Custom credit branding available
4. Commission Credits: 40% lifetime value tracked separately

Agency Pool Management

Agencies managing multiple client accounts can:

• Aggregate credits across client organizations
• Sub-allocate from master pool
• Generate consolidated usage reports
• Apply volume-based top-up discounts

Expiration Policy

Important

All credits expire 90 days from allocation date, regardless of source.

Expiration Rules

1. Subscription Credits: 90 days from monthly refresh
2. Customer Kit Credits: 90 days from kit activation
3. Top-Up Credits: 90 days from purchase date
4. Promotional Credits: Custom expiration (typically 30-90 days)

Expiration Notifications

• 30 Days: Initial warning email
• 7 Days: Urgent reminder with balance
• 1 Day: Final notice before expiration
• Post-Expiration: Credits removed, dashboard updated

Security and Compliance

Access Controls

Credit allocation enforces strict security measures:

• Role-Based Access: Only admins can purchase top-ups
• Audit Logging: All allocation changes tracked
• Fraud Prevention: Unusual consumption patterns flagged
• PCI Compliance: Payment data never stored locally

Data Privacy

• Isolation: Customer Kit usage data segregated
• Encryption: Credit balances encrypted at rest
• GDPR Compliance: Usage data exportable/deletable
• SOC 2: Annual audits verify allocation integrity

API Reference

Get Current Allocation

trpc.credits.getAllocation({
  organizationId: string,
  includeTeams?: boolean,
  includeKits?: boolean
})

// Response
{
  subscription: {
    tier: "Build" | "Sell" | "Scale",
    monthlyAllocation: number,
    currentBalance: number,
    refreshDate: Date
  },
  topUps: {
    balance: number,
    lastPurchase?: Date
  },
  customerKits: [{
    kitId: string,
    balance: number,
    monthlyAllocation: 1000
  }]
}

Purchase Top-Up Credits

trpc.credits.purchaseTopUp({
  organizationId: string,
  mlcAmount: number,
  paymentMethodId?: string // Uses default if not specified
})

// Response
{
  success: boolean,
  newBalance: number,
  transactionId: string,
  expirationDate: Date
}

Best Practices

Allocation Planning

1. Monitor Patterns: Review usage weekly to predict needs
2. Set Budgets: Configure team-level limits to prevent overruns
3. Plan Upgrades: Upgrade tiers before hitting allocation limits
4. Bulk Purchases: Buy top-ups in advance for volume discounts

Partner Optimization

1. Kit Bundling: Group kits for enterprise clients
2. Usage Education: Train customers on credit-efficient practices
3. Allocation Alerts: Proactively notify before exhaustion
4. Upgrade Paths: Guide customers to appropriate tiers

Cost Management

1. Model Selection: Default to efficient models (GPT-4o mini)
2. Prompt Optimization: Reduce token usage through concise prompts
3. Caching Strategy: Implement response caching where appropriate
4. Rate Limiting: Set per-user/per-team consumption caps