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) includes a 14-day free trial. The trial is the refund policy: cancel during the trial and you’re never charged; charge lands on day 15 if you stay subscribed. This page covers the trial mechanics, how the Stripe Customer Portal works, and what happens on payment failure.

​
The trial

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 up-front — no card, no trial. The card is verified at Checkout but not charged.
3

Workspace flips to Builder immediately

On checkout.session.completed (the webhook lands within seconds), workspaces.plan becomes builder. All Builder caps unlock instantly — you don’t have to wait 14 days to use scheduled runs or blocks.create.
4

Trial-end reminder (day 11)

Stripe sends a customer.subscription.trial_will_end webhook 3 days before the trial converts. The receiver logs this for now; an email reminder is a future enhancement.
5

First charge on day 15

Unless you’ve cancelled, Stripe charges the card and the subscription transitions to active. If the charge fails, see Payment failure below.

​
Refund policy

No refunds. The trial is the refund. This is stated in two places:
  1. On the Stripe Checkout page via custom_text.submit.message:
    14-day free trial included. All sales final after the trial.
  2. On /settings/billing in the workspace UI, near the upgrade and portal buttons.
If you cancel during the trial, you pay $0 and the subscription stops at day 14. If you cancel after the trial, 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 during trial vs after

DayStatusBuilder capsCard charged?
0 (checkout)trialingActiveNo
1 – 14trialingActiveNo
15 (first bill)activeActiveYes — full price
Cancelled mid-trialcanceled after day 14Drops back to Free at period endNo
Cancelled after billcanceled at period endBuilder until period end, then FreeAlready charged for current period
The plan literal flips back to "free" when Stripe’s customer.subscription.deleted webhook arrives — usually at the period boundary.

​
Payment failure

If the first charge (or any renewal) 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_endLogged (no email yet).
Receiver runs idempotently — replays from Stripe’s dashboard are safe.

​
Frequently asked

No. The 14-day trial is the refund. Cancel during the trial and you pay $0.
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.