Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chatblocks.ai/llms.txt

Use this file to discover all available pages before exploring further.

Builder (9/moor9/mo or 89/yr) is billed through Stripe Checkout and the Customer Portal. There is no free trial — your card is charged when you complete Checkout. This page covers upgrade mechanics, how the Stripe Customer Portal works, and what happens on payment failure.

​
Upgrading to Builder

1

Upgrade from /settings/billing

Workspace owner only can upgrade. Pick monthly or annual; both run through Stripe Checkout.
2

Provide a card

Card is required. Stripe verifies and charges immediately — there is no trial period.
3

Workspace flips to Builder immediately

On checkout.session.completed (the webhook lands within seconds), workspaces.plan becomes builder. All Builder caps unlock instantly.

​
Refund policy

No published refund policy. If something went wrong, reach out via the support address shown on /settings/billing. Refunds are handled case-by-case in the Stripe Dashboard. If you cancel an active subscription, you keep Builder until the end of the current billing period (no proration, no partial refund), then drop to Free.

​
The Customer Portal

The portal is hosted by Stripe — zero billing UI on our side. From /settings/billing → “Manage subscription,” workspace owners get redirected to a Stripe-hosted page that handles:
  • Plan switching — monthly ↔ annual. Stripe computes the proration.
  • Cancellation — schedules the subscription to end at the period boundary, or cancels immediately (your choice).
  • Card update — replace the saved payment method.
  • Invoice history — every charge and receipt.
The portal session is minted via createPortalSession on the Convex side, which calls stripe.billingPortal.sessions.create. The return URL defaults to https://chatblocks.ai/settings/billing. Owner-only — co-members can’t open the portal.

​
What customers see after subscribing

StatusBuilder capsCard charged?
activeActiveYes — at Checkout and each renewal
Cancelledcanceled at period endBuilder until period end, then FreeAlready charged for current period
past_due / unpaidActive during retry windowRetry in progressSee Payment failure
The plan literal flips back to "free" when Stripe’s customer.subscription.deleted webhook arrives — usually at the period boundary.

​
Payment failure

If a renewal charge fails:
  1. Stripe sends invoice.payment_failed.
  2. Our receiver flips stripeSubscriptionStatus to past_due or unpaid (whatever Stripe set).
  3. Stripe’s smart retry schedule attempts the card again over the next few days.
  4. The workspace stays on Builder during this window — we don’t immediately yank access.
  5. After Stripe gives up (typically ~3 weeks), the subscription cancels and the workspace flips to Free.
To resolve, open the portal and update your card. Stripe retries automatically after a card update.

​
Webhook events the receiver handles

The Convex webhook endpoint is at /webhooks/stripe-billing and dedupes events via billingWebhookEvents.externalEventId. It listens for 6 event types:
EventWhat it does
checkout.session.completedStamps stripeSubscriptionId, flips plan to builder.
customer.subscription.updatedSyncs stripeSubscriptionStatus + stripeCurrentPeriodEnd.
customer.subscription.deletedFlips plan back to free.
invoice.payment_failedUpdates stripeSubscriptionStatus to past_due / unpaid.
invoice.payment_succeededConfirms active + updates period end.
customer.subscription.trial_will_endNo-op kept for any legacy trialing subs in Stripe.
Receiver runs idempotently — replays from Stripe’s dashboard are safe.

​
Frequently asked

No published policy. Reach out via the support address on /settings/billing if you need help.
Existing resources are preserved. New creates fail with LIMIT_REACHED until you delete enough to get under the Free caps. The data isn’t lost — it’s just frozen at over-cap.
Yes — open the Customer Portal, pick annual. Stripe prorates the difference and bills the rest immediately.
Yes. Downgrading doesn’t delete BYOK rows — they just can’t be used while you’re on Free (the panel is gated). Re-upgrading restores access.
No. Upgrade is owner-only. The owner is the immutable ownerAuthUserId set on workspace creation — the paying operator.

​
What’s next

Plans

Pricing and the full cap table.

Workspaces

Owner vs admin vs member — who can do what on a Builder workspace.