Stripe Salesforce Integration: Link Customers to Leads

Connect the Stripe app in Production, import before real-time sync, link each Stripe customer to its Lead by id, and convert only on an active subscription.

By Published

A SaaS company bills in Stripe and sells in Salesforce, and the two rarely agree. Sales cannot see who pays, and nobody trusts which Stripe customer belongs to which Lead or Account. The fix is one shared key, the Stripe customer id, stored on the Salesforce record and linked from both sides.

The steps come from a build in a SaaS company's org. If one buyer already exists as two Leads, fix that first with the duplicate leads guide.

What you need before you start

  • A Salesforce admin with Production and sandbox access.
  • The Stripe account owner, who creates the restricted key and pastes it into the wizard. Stripe says not to share keys over email or chat.
  • Lightning Web Security on, under Setup, Session Settings. Stripe lists it as a prerequisite.
  • A decision on where a paying customer lives: Lead, Account or both.

Step 1: Choose the app, middleware or a custom integration

Choose by what sales needs to see and who will maintain it.

Which way in

What should Salesforce hold?

Customers, subscriptions, invoices

The Stripe app for Salesforce Platform

Stripe's own package adds objects for Customers, Subscriptions, Invoices and Charges, with Real Time or Scheduled sync.

A few fields, a tool you already run

A middleware tool

Writes Salesforce fields from Stripe events, limited to its connectors' triggers and actions.

One status field, a team that writes code

A small custom integration

A webhook endpoint that verifies each Stripe event and upserts the record on an External ID field.

Three ways in. The app brings the most Stripe data with the least code. Illustrative: the shape is the point, not the figures.

The app's default mappings pair Stripe Customer with Account, and Subscription with Contract and Order. Leads are not on that list, which is why steps 4 and 6 exist. A custom build must track event ids, because Stripe says webhook events can arrive out of order and more than once. For high volume, read the platform events buffer pattern.

Step 2: Install the app and connect Production

Stripe offers separate installs for test and production orgs, so install from AppExchange into the one you mean, then follow Stripe's installation guide:

  1. Choose Install for Admins Only and approve third-party access.
  2. Open App Launcher, Stripe for Salesforce Platform, then start the setup wizard, Authorize and Allow.
  3. Enter the publishable key and restricted key, click Add Account, and finish the remaining screens.

The mistake: a sandbox connected, Production never

In the org this guide draws from, the app, the link fields and the flows all reached Production, but nobody ran the wizard there. Only the sandbox was connected, in test mode, so Production held no Stripe account and no customers.

Stripe says to set the app up on each org separately, and its test and live data never mix: test keys start pk_test_ and rk_test_, live keys pk_live_ and rk_live_. In Production, check that the app opens on Account Management with your live account listed, not on the wizard, and that its Customer records include customers you can name.

Then give users access to the app, which Install for Admins Only leaves to you, and a permission set for your link fields. In the build, the link field's permission set had nobody assigned.

Step 3: Import existing customers, then turn on real time

Stripe Billing Sync runs one mode per Stripe account: Real Time, on webhooks, or Scheduled Recurring, which syncs all objects or none.

Import first, then real time

01

Run Scheduled Recurring once

In the Stripe Billing app, set Sync Frequency and Sync Start Time, then enable Scheduled Recurring on the account.

Counts checked against Stripe
02

Switch the account to Real Time

Stripe Billing Sync, Sync Type, Real Time, toggle on.

New changes arrive as they happen, on top of a history you counted.

The order we saw work in one build's sandbox. Illustrative: the shape is the point, not the figures.

A Next Run Time appears under Sync Type once Scheduled is on. Stripe says to manage it in the app, never under Setup, Scheduled Jobs.

After the run, count. In one build's sandbox, the import brought only part of the older test customers and invoices, so treat any import as partial until your counts say otherwise. For older rows, that build planned a separate upsert on the app's Stripe Id field, tested in a sandbox first.

In that build, saving Real Time removed the scheduled import job, and the only order we saw work, in a sandbox, was Scheduled first. Real Time reacts to changes, so a customer who has not changed has nothing to send. Test the same order in your sandbox.

Step 4: Match each Stripe customer to the right record

Add three fields of your own. The names are generic.

FieldObject and typeJob
Stripe_Customer_Id__cLead, Text, External IDThe key
Stripe_Customer__cLead, Lookup to the app's Customer object (stripeGC__Customer__c in one build)Opens subscription, invoices and charges
Stripe_Customer_Id__cAccount, Text, External IDKeeps the key after conversion

Salesforce indexes External ID fields and matches upserts on them, but External ID alone allows duplicates, so we recommend adding Unique once duplicate Leads are merged. Use Map Lead Fields to carry the customer id from the Lead to the Account. Stripe recommends keeping its customer id on your record and your own id in its metadata.

Match in this order:

  1. The Stripe customer id.
  2. Your product's user id from the customer's metadata, copied by the app's Metadata Mappings onto a field you add to its Customer object.
  3. Email, only when exactly one open Lead matches, then write the id onto that Lead. Stripe's email filter is case-sensitive, and Stripe has you create a separate customer for each currency one buyer pays in.

Then link both directions with two record-triggered flows, because either record can arrive first:

  • On Lead, after save, when the id is set or changes: find the Customer whose Stripe Id matches (stripeGC__Stripe_Id__c in one build) and fill the lookup.
  • On the app's Customer, after save, when its Stripe Id is not blank: link every unconverted Lead with that id.

Salesforce notes that Is Changed does not fire on create and suggests adding ISNEW, so we recommend this Lead entry condition:

Code
AND(  OR(ISNEW(), ISCHANGED({!$Record.Stripe_Customer_Id__c})),  NOT(ISBLANK({!$Record.Stripe_Customer_Id__c})))

In one build, both flows routed faults to a quiet end, so a failed link would not block either save.

Step 5: Show subscription status to sales

Keep the status, the customer id and the Customer lookup on the record. Read invoices, charges and payment methods through the linked Customer record, because billing stays Stripe's record. Then decide where each of Stripe's eight subscription statuses lands before anything writes the field:

Stripe statusWhat Stripe meansConvert?
trialingIn a trial periodNo
activeIn good standing, see step 6Yes
incompleteFirst payment due within 23 hoursNo
incomplete_expiredFirst payment never madeNo
past_dueLatest invoice payment failed or not attemptedNo
unpaidRetries ended, no more payment attemptsNo
canceledCanceled, a final stateNo
pausedTrial ended without a payment methodNo

We recommend one writer for each field. In one build, a product sync and the Stripe app were both set up to carry billing data, which is the overlap this rule prevents.

Step 6: Convert the lead only when they pay

Convert on active, never on trialing, because Salesforce says conversion is permanent and cannot be undone. The workaround is deleting the new records and entering the Lead again. A converted Lead is also read-only without the View and Edit Converted Leads permission.

Stripe gives active two exceptions. A subscription billed by invoice, with no trial, starts active before its first invoice is paid, and delayed payment methods such as ACH Direct Debit can go active before the payment clears. If you sell either way, also check for a paid first invoice.

  • Map the Lead fields you need, customer id included, before the first conversion.
  • Convert a short list of named Leads and check each one before a backfill or a replayed event can reach the rule.
  • Let the Account carry the link afterward. In one build, the Customer flow skipped converted Leads.

Step 7: Check it with one count

  1. In Stripe, in live mode, filter Subscriptions to Active and list the distinct customers.
  2. In Salesforce, report Leads with status Active and a filled Customer lookup, and Accounts with status Active and a customer id.
  3. Compare the two lists by customer id, in both directions.

Never count every record with a customer id as paying, because trial and canceled customers have ids too. The build's funnel report did, so count on status.

Every setting on one page

SettingWhere it livesValue in this guide
Lightning Web SecuritySetup, Session SettingsOn
Install optionAppExchange install pageInstall for Admins Only
Stripe accountApp, Account ManagementLive keys, in Production
Scheduled RecurringStripe Billing app, then the accountOnce, first
Sync TypeAccount, Stripe Billing SyncReal Time, after counts match
Customer id fieldLead and AccountText, External ID
Customer lookupLeadThe app's Customer object (stripeGC__Customer__c in one build)
Lead field mappingLead fields, Map Lead FieldsCustomer id, Lead to Account
Conversion ruleYour conversion automationActive only

When the numbers do not match

What you seeLikely causeWhat to check
The app opens its setup wizard in ProductionSetup was done only in a sandboxStep 2
Older customers are missingA partial importStep 3, then upsert the rest
A Customer exists, the Lead is not linkedThe id was set on create under Is ChangedThe Lead entry formula
A payer in Stripe is missing in SalesforceThe id sits on a converted Lead or no recordThe Account's customer id
A payer in Salesforce is missing in StripeA test-mode id on a live recordLook the id up in live mode
A trial counts as payingThe report keys on the customer idReport on status

Before conversion runs on its own

Linking one customer is setup. Letting the link convert Leads and feed revenue reports is a decision, so answer three questions first.

  • Who writes each field? The app, your product or a person, and never two of them.
  • What counts as paying? Active alone, or active with a paid first invoice.
  • Who reconciles the count? Name the person and how often.

Frequently asked questions

Does the Stripe app for Salesforce sync Leads?

Not by default. Its default mappings pair the Stripe Customer with Account. A Lead needs its own Stripe customer id field and a flow that links it to the app's Customer record.

Why does the Stripe app show no customers in Production?

In one build, setup had been finished in a sandbox and never in Production. Stripe says to run setup on each Salesforce org, and test-mode data is not visible from live mode.

Can I undo a lead conversion in Salesforce?

No. Salesforce says conversion is permanent and cannot be undone. The workaround is deleting the new Contact or Account and entering the Lead again by hand.

Official references

GAT Solutions is an independent Salesforce consultancy. Salesforce and AppExchange are trademarks of Salesforce, Inc., and Stripe is a trademark of Stripe, Inc.

Continue the decision

View all resources →

Free consultation

Connecting Stripe to Salesforce? Tell us where it stands.

Never send us a key or password.

See Salesforce integrations

Book a call, or send us what is stuck.

Prefer to talk it through?

Pick a 30-minute time with Gray. Bring the backlog or the thing that broke.

Loading available times…