Stripe connector

The Stripe connector reads your payments, refunds and subscriptions and adds them to each customer profile. Sales also show in the attribution report, and live sales can go to Meta.

It is on paid plans: Solo, Studio, Agency and Custom. Free does not include it.

Sporetag only reads. The key you give it cannot charge, refund or change anything in Stripe.

Connect

1. In Sporetag, open your site, then Integrations. Next to Stripe, click Connect. 2. In Stripe, open API keys and click Create restricted key. If Stripe asks how you will use the key, pick the option for another app or website. 3. Name it Sporetag. Set these to Read and leave everything else at None: - Customers - Charges - PaymentIntents - Checkout Sessions - Invoices - Refunds - Subscriptions 4. Click Create key. Stripe may ask for a code it sends you. Copy the key. It starts with rk_live_. 5. Paste it into Sporetag and click Connect Stripe.

Sporetag checks that the key can read each of the seven. If one is missing, it says which one. Use a test key (rk_test_) to try it with test data first.

Do not paste your secret key (sk_live_). It can do anything in your account, so Sporetag refuses it.

What happens next

• The first import reads the last 90 days. A busy account can take a few hours, since each run reads a small batch. The Integrations tab shows Importing and a count.
• After that, Sporetag checks for new payments every 15 minutes.
• Sync now starts a check at once.

The key is stored encrypted. It is never shown again, and it never appears in logs.

Instant updates (optional)

Without a webhook, new sales show up within 15 minutes. With one, they show up in seconds, and a live sale can go to Meta right away.

1. Open the Stripe connector's page in Sporetag (Settings next to Stripe). Copy the Endpoint URL. It looks like https://sporetag.com/hooks/stripe/.... 2. In Stripe, open Webhooks and add an endpoint. Stripe may call it an event destination. 3. Pick these events: - checkout.session.completed - charge.succeeded - charge.refunded - invoice.paid - customer.subscription.created - customer.subscription.deleted 4. Paste the endpoint URL and save. 5. Reveal the endpoint's Signing secret (it starts with whsec_), copy it, and paste it into Sporetag under Instant updates.

Sporetag checks the signature on every webhook and refuses any that do not match. It then reads the payment again from Stripe with your key, so it never trusts the webhook body alone.

What shows up on a customer

One payment is one order. A Checkout Session, its PaymentIntent, its charge and its invoice are linked, so Stripe telling us about each of them never counts the sale twice.

Orders and revenue add up into the customer's lifetime value. Revenue adds up in the customer's first currency.

Who the customer is

Sporetag finds the customer by:

• the Stripe customer id,
• the email and phone on the payment (hashed with SHA-256, the way Meta asks),
• the visitor's first-party id in metadata.st_id.

With the first-party id, the sale ties to the visits, ads and short links that came before it. That needs the site in Attribution mode. Copy the _st_id cookie into the metadata when you create the Checkout Session:

const session = await stripe.checkout.sessions.create({
  // ...your line items, mode and URLs
  metadata: { st_id: req.cookies._st_id },
});

For a PaymentIntent, set the same metadata.st_id on the PaymentIntent. For a subscription, set it on the subscription.

Without it, the sale still joins the customer by email or Stripe id. It shows on their profile, but it can only be tied to an ad if that customer was identified on your site before.

Goals and Meta

Synced sales count as the Purchase event. They reach any goal on the event Purchase.

When that goal is set to send to Meta (see Meta Conversions API), a new sale goes to Meta once:

• Only live sales: ones that happened in the last 24 hours. The 90-day import never sends old sales.
• Renewals are not sent. They are not new buyers.
• The hashed email and phone go along, so Meta can match the buyer.

The event_id rule

Meta and Sporetag both count a sale once per event_id. The Stripe connector uses the Stripe object id:

If you also send the sale from the browser or the Events API, use the same id as event_id. For Checkout, your success page gets the session id when the success URL has ?session_id={CHECKOUT_SESSION_ID}:

sporetag('Purchase', { event_id: sessionId, value: 49, currency: 'USD' });
fbq('track', 'Purchase', { value: 49, currency: 'USD' }, { eventID: sessionId });

Then:

• Sporetag sees the same id from both and counts the order once on the customer.
• A sale already sent to Meta from the browser or the Events API is not sent again by the connector, and the other way round.
• Meta also drops the second copy it gets from the pixel.

An order_id that matches one of the Stripe ids is treated the same way.

The attribution report

Synced sales appear in the attribution report on their real date, under All goals and under a goal on Purchase. A sale that your site also sent as an event, with the same event_id or order_id, is counted once.

Synced sales do not change your visitor stats and do not count toward your plan's events.

Sync log

The connector's page lists the last 50 runs and webhooks: what was added and any errors. Keys and personal data are never shown there. Rows older than 30 days are deleted.

If something goes wrong

The Integrations tab shows Needs attention with the reason:

• Stripe did not accept the key. It was deleted or expired. Make a new restricted key and paste it under Paste a new key.
• The key cannot read Invoices (or another resource). Edit the key in Stripe and set it to Read.
• Stripe is busy right now. Nothing to do. Sporetag tries again in 15 minutes.
• Paused. Connectors are on paid plans. The plan changed to Free. Sync starts again after an upgrade.

Disconnect

Click Disconnect on the connector's page. The key and the signing secret are deleted at once. Orders already imported stay on your customers. To remove one person's data, use Delete this customer on their profile. Delete the restricted key and the webhook in Stripe too.

If you connect again later, the endpoint URL stays the same.