Stripe Connect for the Kustiq churn engine.

Overview

The Stripe Connect integration is the input source for Kustiq’s churn engine. It reads subscription, charge, and customer data on your Stripe account and turns it into a churn-risk score on every matched paying customer. It does not run Kustiq’s own billing, and it does not run your reporting.

One direction, Stripe to Kustiq. We never call POST, PATCH, or DELETE against your Stripe account: a code-level guard blocks every non-GET request to the Stripe API and raises an error instead of mutating anything. 5 signal families feed the engine: MRR delta, payment failures, downgrades, days since last charge, and subscription status. The full list is in the Signal reference below.

With the integration on, a customer with fresh payment failures in the last 30 days moves to the top of the at-risk segment on the next sync. With Stripe alone, the same signal stays in the dashboard event log nobody scrolls.

Setup, in 4 minutes

Five steps. Stripe-side OAuth, no API key paste, no restricted-key creation. You can revoke the grant from your Stripe dashboard at any time, and Kustiq’s client refuses to send anything but reads.

Signal reference

Five signal families, read from three Stripe objects per customer during sync: subscriptions, lifetime charges, and the last 30 days of subscription update events. Nothing else on your account is read, so extra products or events cost you nothing and do not affect the score.

Permissions and scopes

Stripe’s current Connect OAuth offers one standard grant for new platforms, so read-only is enforced on Kustiq’s side: an HTTP-layer guard blocks every non-GET request to the Stripe API and raises an error instead of mutating anything. The grant is revocable from Stripe → Settings → Connected apps without contacting support. What Kustiq actually reads:

• Customers · name, email, metadata. Used for matching and tenure features.
• Subscriptions · status, plan, interval, cancellation and pause state. Drives the status and downgrade signals.
• Charges · amount, status, attempt history, lifetime totals. Drives the dunning signal and the CLTV floor.
• Subscription update events · last 30 days. Drives downgrade and MRR-delta detection.

Kustiq does not read balances, transfers, payouts, tax records, or bank data, and never issues a write. If your IT review asks for a written list of what we touch, the four lines above are the answer.

Outbound webhooks

Kustiq does not register webhooks on your Stripe account; every sync is a read. Webhooks go the other way: on Pro you can register up to 5 endpoints and Kustiq POSTs signed events like churn.score_changed when a sync moves a score. The snippet below is the verification we recommend on your side.

// Express handler. Use express.raw({ type: "application/json" }).
const crypto = require("crypto");
const SECRET = process.env.KUSTIQ_WEBHOOK_SECRET;

function verify(req) {
  const sig = req.headers["x-kustiq-signature"] || "";
  if (sig.length !== 64) return false;

  const mac = crypto
    .createHmac("sha256", SECRET)
    .update(req.body)
    .digest("hex");

  const ok = crypto.timingSafeEqual(
    Buffer.from(mac, "hex"),
    Buffer.from(sig, "hex"),
  );
  if (!ok) return false;

  // Replay check: body has top-level "timestamp" (unix seconds).
  const body = JSON.parse(req.body);
  return Date.now() / 1000 - body.timestamp < 300;
}

Each request is signed with HMAC-SHA256 over the raw body; the signature is a bare 64-character hex digest in the X-Kustiq-Signature header, and the body carries a top-level unix timestamp for replay protection. Retry policy: a non-2xx response or no response inside 10s triggers one retry 5 seconds later, then the event is dropped; every attempt is logged with status code and latency.

Sync rules

• Cadence. On demand plus daily. You run the first sync at connect time; after that Kustiq refreshes signals once a day and whenever you press Sync now.
• Direction. One way, Stripe to Kustiq. The integration never writes, updates, refunds, or cancels anything on your account; a code-level guard blocks every non-GET request.
• Mode.The account you pick on Stripe’s consent screen decides live vs test. Reconnect to switch.
• Match key. Saved Stripe customer ID first (set automatically after the first match, or manually per profile), customer email domain second. Unmatched customers never feed a score.
• Coverage. Charges are read all-time so lifetime revenue is right; subscription update events use a 30-day window. Customers are paged 100 at a time.
• Rate limit.Stripe’s read API limits apply during sync; live mode caps at 100 req / sec, test mode at 25.

Trust and data handling

This section is the answer to your IT review. What we store, what we never touch, where it lives.

Data lives where the rest of the platform lives: the primary database is Supabase (US East) and API workers run on Hetzner in the EU. There is no per-workspace region picker. Full DPA at /dpa, security posture at /trust.

Disconnect

Two paths. From Stripe: Stripe → Settings → Connected apps → Kustiq → Revoke access. From Kustiq: Settings → Integrations → Stripe → Disconnect. Disconnecting from Kustiq calls Stripe’s deauthorize endpoint and deletes the stored tokens immediately; all reads stop with the grant.

Troubleshooting

Five known states. Each has a stable anchor so you can link a teammate to the exact row.

FAQ

Changelog

• 2026-05-16 · v1.1 Pair-lock production-ready audit. BreadcrumbList position-1 fixed to “Home”. SoftwareApplication JSON-LD @id-graph linked to root #org and #site. New per-page OG image at /docs/stripe/opengraph-image. FAQ trust-card reference converted to anchor link. Free-tier copy unified to 3 profiles a week. Eleven → 11 numeric consistency.
• 2026-05-08 · v1.0 Initial release. Disambiguation banner against billing-docs collision. Pro-plan link on the lede. Trust section above Disconnect. Footer cross-link row. Last-verified badge.
• 2026-04-17 · v0.9 Stripe Connect integration shipped: OAuth flow, read guard, daily churn-signal sync.