Connect Stripe

Updated 2026-11-02

Beta

Connecting Stripe is in beta.

Connect

1. Open Project in the dashboard and find the Stripe card.
2. Click Connect Stripe with read-only access.
3. Approve the connection in Stripe.

Agents can get the link from stripeConnectUrl in GET /api/v1/status, but you have to open it while signed in.

You need permission to manage the project. A Stripe account can connect to one project. To share an account across a marketing site and an app, add both domains to the same project.

What gets imported

Headstream asks for Stripe's read_only scope. It imports successful charges, then refunds, then disputes. The change log records how many of each. New activity then arrives by webhook:

• charge.succeeded
• refund.created
• charge.dispute.funds_withdrawn
• charge.dispute.funds_reinstated

Everything goes in an append-only ledger. A refund is a new negative row. A dispute adds a negative row when Stripe takes the money, and a positive one if it comes back.

How payments link to people

For each charge, Headstream looks for a person in this order:

1. A person with the same Stripe customer ID
2. The browser in the charge metadata key headstream_visitor
3. A person with the same billing email

Once a charge matches, the Stripe customer ID is saved to that person, so renewals match too.

Make matches reliable

The simplest step is to identify people with the email they pay with. If you know the Stripe customer ID, send it:

window.headstream?.identify({ email, stripeCustomerId: "cus_123" });

For a one-time Stripe Checkout, you can pass the visitor directly. Read the hs_vid cookie on your server and add it to the charge. The browser needs to have been identified at some point for this to link.

await stripe.checkout.sessions.create({
  mode: "payment",
  payment_intent_data: { metadata: { headstream_visitor: visitorId } },
  // the rest of your session
});

Attribution

Attribution runs hourly for all four models. A run publishes only if credits equal the ledger, so a new payment appears after the next successful run. Refunds and disputes credit back to the original sale.

Each session in the lookback window counts as a visit. The window defaults to 90 days. Change it under Project details. Payments with no match appear as Unattributed.

Check your numbers

• Revenue: compare with Stripe.
• Data quality: shows Stripe reconciliation and the latest run.
• Payment trail: traces one entry to every credited visit. See the API.

Payments in other currencies are reported separately.