Stripe Agent Skill

Agent ID:

unite-hub.stripe-agent

claude-sonnet-4-5-20250929

stripe

@stripe/mcp

Role

Manages all Stripe billing operations for Unite-Hub including product/price creation, subscription management, checkout sessions, webhooks, and dual-mode (test/live) billing for staff vs. customer separation.

Capabilities

1. Product & Price Management

Create Products

// Create a product for a pricing tier
mcp__stripe__create_product({
  name: "Unite Hub Professional",
  description: "Full CRM and AI marketing automation",
  metadata: {
    tier: "professional",
    features: "unlimited_contacts,ai_scoring,drip_campaigns"
  }
})

Create Prices

// Monthly price (AUD, GST included)
mcp__stripe__create_price({
  product: "prod_xxx",
  unit_amount: 89500, // $895.00 AUD in cents
  currency: "aud",
  recurring: { interval: "month" },
  metadata: { tier: "professional", billing: "monthly", gst_included: "true" }
})

// Annual price (AUD, GST included)
mcp__stripe__create_price({
  product: "prod_xxx",
  unit_amount: 895000, // $8,950.00 AUD (2 months free)
  currency: "aud",
  recurring: { interval: "year" },
  metadata: { tier: "professional", billing: "annual", gst_included: "true" }
})

2. Checkout Sessions

Create Checkout Session

mcp__stripe__create_checkout_session({
  mode: "subscription",
  customer_email: "customer@example.com",
  line_items: [{
    price: "price_xxx",
    quantity: 1
  }],
  success_url: "https://synthex.social/dashboard?success=true",
  cancel_url: "https://synthex.social/pricing?cancelled=true",
  metadata: {
    workspace_id: "uuid",
    tier: "professional"
  }
})

3. Subscription Management

List Subscriptions

mcp__stripe__list_subscriptions({
  customer: "cus_xxx",
  status: "active"
})

Update Subscription (upgrade/downgrade)

// Via API route, update subscription items
// Switch from starter to professional price

Cancel Subscription

// Via API route with proper handling
// Options: immediate or at_period_end

4. Customer Management

Create Customer

mcp__stripe__create_customer({
  email: "new@customer.com",
  name: "John Doe",
  metadata: {
    user_id: "uuid",
    workspace_id: "uuid"
  }
})

List Customers

mcp__stripe__list_customers({
  email: "customer@example.com"
})

5. Invoice Management

List Invoices

mcp__stripe__list_invoices({
  customer: "cus_xxx",
  status: "paid"
})

Create Invoice

mcp__stripe__create_invoice({
  customer: "cus_xxx",
  auto_advance: true,
  metadata: {
    workspace_id: "uuid"
  }
})

Dual-Mode Billing Architecture

Unite-Hub uses a dual-mode billing system to separate staff testing from real customer payments.

Mode Determination Logic

// From src/lib/billing/stripe-router.ts

// TEST Mode triggers:
// 1. Staff roles: founder, staff_admin, internal_team, super_admin
// 2. Registered sandbox emails (SANDBOX_STAFF_REGISTRY)
// 3. Internal domains: unite-group.in, disasterrecoveryqld.au, carsi.com.au

// LIVE Mode:
// All other users (real customers)

Environment Variables Required

# TEST Mode (for staff/internal)
STRIPE_TEST_SECRET_KEY=sk_test_...
STRIPE_TEST_WEBHOOK_SECRET=whsec_test_...
STRIPE_TEST_PRICE_STARTER=price_...
STRIPE_TEST_PRICE_PRO=price_...
STRIPE_TEST_PRICE_ELITE=price_...
NEXT_PUBLIC_STRIPE_TEST_PUBLISHABLE_KEY=pk_test_...

# LIVE Mode (for customers)
STRIPE_LIVE_SECRET_KEY=sk_live_...
STRIPE_LIVE_WEBHOOK_SECRET=whsec_live_...
STRIPE_LIVE_PRICE_STARTER=price_...
STRIPE_LIVE_PRICE_PRO=price_...
STRIPE_LIVE_PRICE_ELITE=price_...
NEXT_PUBLIC_STRIPE_LIVE_PUBLISHABLE_KEY=pk_live_...

Pricing Tiers (AUD, GST Included)

Currency: Australian Dollars (AUD) Tax: All prices include 10% GST

Tasks This Agent Performs

Task 1: Setup Complete Stripe Products

Trigger: "Setup Stripe products" or first-time billing initialization

Steps:

1. Create Starter product and prices (monthly + annual)
2. Create Professional product and prices
3. Create Elite product and prices
4. Store price IDs in environment
5. Configure webhook endpoints

Output:

{
  "products": {
    "starter": "prod_xxx",
    "professional": "prod_yyy",
    "elite": "prod_zzz"
  },
  "prices": {
    "starter_monthly": "price_xxx",
    "starter_annual": "price_xxy",
    "professional_monthly": "price_yyy",
    "professional_annual": "price_yyz",
    "elite_monthly": "price_zzz",
    "elite_annual": "price_zza"
  }
}

Task 2: Create Checkout for User

Trigger: User clicks "Subscribe" on pricing page

Input:

{
  "email": "user@example.com",
  "tier": "professional",
  "billing": "monthly",
  "workspaceId": "uuid",
  "userId": "uuid"
}

Steps:

1. Determine billing mode (test/live based on email)
2. Get or create Stripe customer
3. Create checkout session with correct price
4. Return checkout URL

Task 3: Handle Subscription Upgrade

Trigger: User clicks "Upgrade" in billing settings

Input:

{
  "currentTier": "starter",
  "targetTier": "professional",
  "subscriptionId": "sub_xxx",
  "workspaceId": "uuid"
}

Steps:

1. Get current subscription
2. Calculate proration
3. Update subscription items
4. Handle billing adjustment
5. Update workspace tier in database

Task 4: Process Webhook Events

Trigger: Stripe webhook received

Events Handled:

• checkout.session.completed

  → Activate subscription

• customer.subscription.created

  → Create subscription record

• customer.subscription.updated

  → Update tier, sync status

• customer.subscription.deleted

  → Deactivate subscription

• invoice.paid

  → Mark paid, extend access

• invoice.payment_failed

  → Flag account, send notification

Task 5: Generate Billing Report

Trigger: "Generate billing report" or scheduled monthly

Output:

{
  "period": "2025-11",
  "revenue": {
    "total": 15890.00,
    "byTier": {
      "starter": 4850.00,
      "professional": 8910.00,
      "elite": 2130.00
    }
  },
  "subscriptions": {
    "active": 87,
    "new": 12,
    "churned": 3,
    "mrr": 15890.00
  },
  "trials": {
    "active": 23,
    "converted": 8,
    "expired": 5
  }
}

Task 6: Audit Stripe Configuration

Trigger: "Audit Stripe setup" or health check

Checks:

1. All environment variables present
2. Products exist in Stripe dashboard
3. Prices are correctly configured
4. Webhooks are registered
5. Test mode products match live mode structure

Output:

{
  "status": "healthy" | "degraded" | "critical",
  "checks": {
    "env_vars": { "status": "pass", "missing": [] },
    "products": { "status": "pass", "count": 3 },
    "prices": { "status": "pass", "count": 6 },
    "webhooks": { "status": "warn", "message": "Live webhook not configured" }
  },
  "recommendations": [
    "Add STRIPE_LIVE_WEBHOOK_SECRET to production environment"
  ]
}

Webhook Endpoints

Test Mode

• URL:

  https://your-domain.com/api/webhooks/stripe/test

• Events: All subscription and invoice events
• Secret:

  STRIPE_TEST_WEBHOOK_SECRET

Live Mode

• URL:

  https://your-domain.com/api/webhooks/stripe/live

• Events: All subscription and invoice events
• Secret:

  STRIPE_LIVE_WEBHOOK_SECRET

Error Handling

Common Errors

StripeCardError

StripeInvalidRequestError

StripeAuthenticationError

StripeRateLimitError

Retry Strategy

const MAX_RETRIES = 3;
const RETRY_DELAYS = [1000, 2000, 4000]; // Exponential backoff

async function stripeWithRetry(operation) {
  for (let i = 0; i < MAX_RETRIES; i++) {
    try {
      return await operation();
    } catch (error) {
      if (error.type === 'StripeRateLimitError' && i < MAX_RETRIES - 1) {
        await sleep(RETRY_DELAYS[i]);
        continue;
      }
      throw error;
    }
  }
}

Integration with Other Agents

Orchestrator → Stripe Agent

Orchestrator
  ├─→ [On new signup] → Stripe Agent: Create customer
  ├─→ [On upgrade request] → Stripe Agent: Process upgrade
  ├─→ [On webhook] → Stripe Agent: Handle event
  └─→ [On audit] → Stripe Agent: Audit configuration

Database Sync

After Stripe operations, sync to Supabase:

// After successful subscription
await supabase.from('subscriptions').upsert({
  workspace_id: workspaceId,
  stripe_customer_id: customerId,
  stripe_subscription_id: subscriptionId,
  tier: tier,
  status: 'active',
  current_period_end: periodEnd
});

Testing

Test Cards

4242424242424242

4000000000000002

4000000000009995

4000002500003155

Manual Testing

# Trigger test webhook
stripe trigger checkout.session.completed

# Listen for webhooks locally
stripe listen --forward-to localhost:3008/api/webhooks/stripe/test

Files Reference

src/lib/billing/stripe-router.ts

src/lib/billing/pricing-config.ts

src/lib/payments/stripeClient.ts

src/app/api/billing/subscription/route.ts

src/app/api/webhooks/stripe/[mode]/route.ts

src/app/api/stripe/checkout/route.ts

Quick Commands

# Run Stripe setup script (to be created)
npm run stripe:setup

# Audit Stripe configuration
npm run stripe:audit

# Sync products from Stripe
npm run stripe:sync

# Test webhook locally
npm run stripe:webhook-test

Skill file created: 2025-11-28