What Stripe permissions does Kustiq need?

Kustiq authorizes via Stripe Connect and only calls read endpoints — customers, subscriptions, charges, and events. Stripe restricts the narrower read_only scope to platforms that have requested it in advance, so Kustiq currently rides the default scope while performing no writes. No charges, no refunds, no subscription changes ever.

How does Kustiq match Stripe customers to my profiles?

Matching precedence: (1) a manual stripe_customer_id override on the profile row wins; (2) otherwise Kustiq extracts the business domain from the customer's email (personal domains like Gmail are skipped) and matches it to a profile with the same domain; (3) on first auto-match Kustiq persists the Stripe customer ID back to the profile so the next sync is O(1).

What if a customer pays from a personal email domain?

Gmail, Yahoo, Outlook, iCloud, and other personal email providers are skipped for domain auto-match to avoid false positives across customers. Set a manual stripe_customer_id on that profile via the /customer-mapping endpoint to force a match.

Which billing signals feed the churn engine?

Five signal types: stripe_mrr_delta (current MRR), stripe_subscription_status (active / past_due / canceled plus dunning flag), stripe_payment_failure (failed charges in the trailing 30 days), stripe_days_since_charge (days since most recent successful charge), stripe_downgrade (plan change with lower amount within 30 days).

How often does the sync run?

Daily at 5:45 UTC via a cron job inside the Kustiq API container. Pro-plan admins can also trigger an ad-hoc sync from the integrations page via the Sync now button.

Will connecting Stripe change my existing churn scores?

Yes — customers previously scored with only the CRM family now have two behavioural families (CRM + billing), which triggers the classifier-weight redistribution rule. The classifier's churn_risk factor multiplies by 0.4 instead of 0.7, so the score is more weighted toward observed behaviour. Expect visible score shifts on day 1.

How do I disconnect Stripe?

On the Integrations page, click Disconnect on the Stripe card. Kustiq runs Stripe's OAuth deauthorize endpoint to revoke its access token and nulls the local credentials. Any emitted usage_signals stay in your history so past churn scores remain explainable.

Stripe Integration

Connect your Stripe account to feed the churn engine's billing signal family. Kustiq only reads — never writes to your Stripe data. Available on the Pro plan.

Last updated: April 17, 2026

3-minute setup

Overview

Kustiq's churn engine blends seven signal families. The billing family is the strongest single family (max_abs_impact=30) because payment failures, dunning, and cancellation are near-ground-truth churn indicators. Without Stripe, churn scores lean on the classifier and whatever CRM signals you've supplied; connecting Stripe lets Kustiq replace classifier guesses with observed financial behaviour.

Signal types

For each matched customer, the nightly sync emits up to five usage_signals rows that the StripeProvider turns into churn factors.

Signal	Fires a factor when	Impact
stripe_subscription_status	Status is canceled	+15
stripe_subscription_status	Any subscription is past_due (dunning)	+10
stripe_payment_failure	≥ 3 failed charges in 30 days	+12
stripe_payment_failure	1-2 failed charges in 30 days	+6
stripe_downgrade	Plan amount dropped within 30 days	+10
stripe_days_since_charge	≥ 45 days without a successful charge	+8
stripe_mrr_delta	MRR declining > 10% over 90 days	+10
stripe_mrr_delta	MRR growing > 10% over 90 days	−8

The summed factor impact is clamped to [-30, +30] per customer so a single mis-classified event can't dominate the score.

How customer matching works

Kustiq pairs each Stripe customer with a Kustiq profile in the following order:

Manual override. If the profile already has a stripe_customer_id that matches the incoming Stripe customer ID, it wins. Set this via PATCH /api/v1/integrations/stripe/customer-mapping/{profile_id} for bulk cases or unusual matches.
Email domain. Kustiq extracts the business domain from the Stripe customer's email (or metadata.domain), skips personal providers (Gmail, Yahoo, etc.), and matches the remaining domain to a profile with the same domain.
Persist auto-match. On first auto-match, Kustiq writes the Stripe customer ID back to the profile so the next sync is O(1). Subsequent syncs hit the manual-override path at (1).

Expect visible score shifts on day one

Connecting Stripe typically lifts a profile from one behavioural family (CRM only) to two (CRM + billing). The churn engine's classifier-weight redistribution rule then multiplies the classifier's churn_risk factor by 0.4 (down from 0.7 with one family). Scores skew more toward observed billing behaviour and away from LLM guesses — exactly the intended effect, but a visible shift on day one.

Sync schedule

The Stripe sync cron runs at 5:45 UTC daily (15 minutes after the HubSpot cron at 5:30). Pro-plan admins can also kick an ad-hoc sync from the Integrations page via the Sync now button. Rate limits stay well under Stripe's 100 req/sec ceiling.

Disconnecting

Click Disconnect on the Stripe card. Kustiq runs Stripe's OAuth deauthorize endpoint to revoke access server-side and nulls the local credentials. Previously-emitted usage_signals stay so past churn scores remain explainable. Future scoring no longer includes the billing family until you reconnect.

Go to Integrations View churn dashboard