Billing & Subscriptions

Billing & Subscriptions

Huitzo uses Stripe for subscription management. This guide covers subscription tiers, rate limits, and the billing API.

Subscription Tiers

Tier Price Requests/min Commands/hour Features
Free $0 10 5 Basic access, community support
Developer Preview $0 (invite-only) 60 Unlimited Early access, founding member benefits
Pro $50/month 300 Unlimited Priority support, advanced analytics, custom integrations
Enterprise Custom 1000 Unlimited Dedicated support, SLA, custom deployment

Checking Your Tier

# Via CLI
huitzo status

# Via API
curl -H "Authorization: Bearer $TOKEN" \
  https://huitzo.ai/api/v1/billing/status

Response:

{
  "data": {
    "subscription_tier": "developer_preview",
    "stripe_customer_id": null,
    "cohort": "founding-feb15"
  }
}

Upgrading to Pro

Via Dashboard

  1. Navigate to Settings > Billing
  2. Click Upgrade to Pro - $50/month
  3. Complete payment on the Stripe Checkout page
  4. Your tier is upgraded immediately upon successful payment

Via API

# Create checkout session
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"success_url": "https://hub.huitzo.com/billing?success=true", "cancel_url": "https://hub.huitzo.com/billing"}' \
  https://huitzo.ai/api/v1/billing/checkout

Response:

{
  "data": {
    "checkout_url": "https://checkout.stripe.com/..."
  }
}

Redirect the user to checkout_url to complete payment.

Managing Your Subscription

Use the Stripe Customer Portal to update payment methods, view invoices, or cancel:

curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"return_url": "https://hub.huitzo.com/billing"}' \
  https://huitzo.ai/api/v1/billing/portal

Rate Limiting

All API requests include rate limit headers:

Header Description
X-RateLimit-Remaining Requests remaining in current window
Retry-After Seconds to wait before retrying (on 429)

When rate limited, you'll receive a 429 Too Many Requests response.

Webhook Events

Huitzo processes these Stripe webhook events:

Event Action
checkout.session.completed Upgrade user to Pro
customer.subscription.updated Sync subscription status
customer.subscription.deleted Downgrade to Free
invoice.payment_succeeded Log successful payment
invoice.payment_failed Log failed payment

API Reference

Endpoint Method Auth Description
/api/v1/billing/status GET User Current subscription status
/api/v1/billing/plans GET Public List available plans
/api/v1/billing/checkout POST User Create Stripe Checkout session
/api/v1/billing/portal POST User Create Stripe Customer Portal session
/api/v1/billing/webhook POST Stripe sig Handle Stripe webhook events