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.

The Stripe connector pulls live numbers from your Stripe account on a refresh cadence (cron) or in real time (webhook push). Bind a block to a Stripe query, declare a projection, and the platform keeps widget.data fresh.

​
Add a Stripe data source

1

Go to the wizard

/settings/data-sources/new/stripe (or click “New data source” from /settings/data-sources and pick Stripe).
2

Paste a restricted API key

Read-only is sufficient — the connector never writes back to Stripe. Generate a restricted key from your Stripe dashboard scoped to Read on Subscriptions, Charges, and Balance.The plaintext is envelope-encrypted with your workspace’s DEK before it’s written to Convex. We never log or display it.
3

Optionally paste a webhook signing secret

Skipping this puts the source in cron-mode — the platform polls Stripe on a cadence you pick (5, 15, 60, 360, or 1440 minutes).Providing a signing secret enables push-mode — Stripe POSTs subscription / charge / balance events to a Convex webhook endpoint and the platform refreshes within seconds. The cadence dropdown still controls a safety-net background poll.
4

Save

The wizard validates the key against Stripe’s API and saves on success. You’re sent back to the data-sources list with the new source visible (label, type, cadence, status).
Free workspaces can have at most one Stripe data source. Builder lifts the cap. See Plans and limits.

​
Query catalog

Three first-class queries. See apps/web/convex/lib/connectors/stripeQueries.ts for the implementations.
Sums the unit_amount of every active subscription, paginated across the full set.Result:
{
  amount_cents: number;
  currency: string;
}
Use for an MRR metric widget.
Calls /v1/balance and returns the available + pending breakdown.Result:
{
  available_cents: number;
  pending_cents: number;
  currency: string;
}
Use for a “what’s my Stripe balance” widget.
Lists the most recent N charges (default 10, max 100).Result:
{
  charges: Array<{
    id: string;
    amount_cents: number;
    currency: string;
    status: string;
    created_at_unix: number;
    customer_email: string | null;
  }>;
}
Use for a recent-activity list widget.

​
Bind a block

In the block’s chatblocks.json: 
{
  "binding": {
    "dataSourceId": "<stripe-data-source-id>",
    "queryConfig": {
      "type": "stripe.mrr",
      "params": {}
    },
    "projection": {
      "fields": {
        "value": { "source": "amount_cents", "format": "currency" },
        "label": { "literal": "MRR" }
      }
    }
  },
  "widget": {
    "template": "metric",
    "data": { "value": "$0", "label": "MRR" }
  }
}
The aggregator runs stripe.mrr on the configured cadence, applies the projection to map amount_cents → a formatted currency string, writes the result into widget.data, and pushes to iOS. Projection format helpers (currency, number, percent, percent-with-sign, datetime) live in packages/shared/src/projection.ts. They’re pure functions — same input → same output, no side effects.

​
Refresh modes

Default. The platform polls Stripe at cadenceMinutes (5 / 15 / 60 / 360 / 1440). A 1-minute Convex cron scans active data sources and dispatches refreshes for any whose lastRefreshAt + cadenceMinutes < now.Per-binding failures don’t poison the source — one failing query won’t stop the others from refreshing. A source-level auth failure (revoked API key, etc.) sets lastErrorMessage on the source and surfaces in the data-sources list.

​
Credential storage and audit

The credential blob is JSON: { apiKey, webhookSecret? }. Encrypted via the workspace DEK (envelope encryption with a master KEK in Convex env). Every decryption — every refresh — writes an auditLog row stamped actor: "system:scheduledRunner" or actor: "system:stripeWebhook" so you can see exactly when the key was used. See Audit log for the full event surface.

​
What’s next

Postgres

Point at your own Postgres and write SQL queries with platform-side safety wrapping.

Webhook

Receive arbitrary JSON from your own systems with HMAC-signed delivery.