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.
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:
- Choose Install for Admins Only and approve third-party access.
- Open App Launcher, Stripe for Salesforce Platform, then start the setup wizard, Authorize and Allow.
- 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
Run Scheduled Recurring once
In the Stripe Billing app, set Sync Frequency and Sync Start Time, then enable Scheduled Recurring on the account.
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.
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.
| Field | Object and type | Job |
|---|---|---|
Stripe_Customer_Id__c | Lead, Text, External ID | The key |
Stripe_Customer__c | Lead, Lookup to the app's Customer object (stripeGC__Customer__c in one build) | Opens subscription, invoices and charges |
Stripe_Customer_Id__c | Account, Text, External ID | Keeps 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:
- The Stripe customer id.
- 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.
- 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__cin 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:
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 status | What Stripe means | Convert? |
|---|---|---|
trialing | In a trial period | No |
active | In good standing, see step 6 | Yes |
incomplete | First payment due within 23 hours | No |
incomplete_expired | First payment never made | No |
past_due | Latest invoice payment failed or not attempted | No |
unpaid | Retries ended, no more payment attempts | No |
canceled | Canceled, a final state | No |
paused | Trial ended without a payment method | No |
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
- In Stripe, in live mode, filter Subscriptions to Active and list the distinct customers.
- In Salesforce, report Leads with status Active and a filled Customer lookup, and Accounts with status Active and a customer id.
- 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
| Setting | Where it lives | Value in this guide |
|---|---|---|
| Lightning Web Security | Setup, Session Settings | On |
| Install option | AppExchange install page | Install for Admins Only |
| Stripe account | App, Account Management | Live keys, in Production |
| Scheduled Recurring | Stripe Billing app, then the account | Once, first |
| Sync Type | Account, Stripe Billing Sync | Real Time, after counts match |
| Customer id field | Lead and Account | Text, External ID |
| Customer lookup | Lead | The app's Customer object (stripeGC__Customer__c in one build) |
| Lead field mapping | Lead fields, Map Lead Fields | Customer id, Lead to Account |
| Conversion rule | Your conversion automation | Active only |
When the numbers do not match
| What you see | Likely cause | What to check |
|---|---|---|
| The app opens its setup wizard in Production | Setup was done only in a sandbox | Step 2 |
| Older customers are missing | A partial import | Step 3, then upsert the rest |
| A Customer exists, the Lead is not linked | The id was set on create under Is Changed | The Lead entry formula |
| A payer in Stripe is missing in Salesforce | The id sits on a converted Lead or no record | The Account's customer id |
| A payer in Salesforce is missing in Stripe | A test-mode id on a live record | Look the id up in live mode |
| A trial counts as paying | The report keys on the customer id | Report 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
- Stripe Docs: Stripe app for Salesforce Platform
- Stripe Docs: app installation
- Stripe Docs: app configuration
- Stripe Docs: API keys
- Stripe Docs: Customers
- Stripe API: list all customers
- Stripe Docs: subscription statuses
- Stripe Docs: webhook endpoints
- Salesforce Help: undo lead conversion
- Salesforce Help: considerations for converting leads
- Salesforce Help: map lead fields for conversion
- Salesforce Help: External ID and Unique ID
- Salesforce Help: External ID indexing
- Salesforce Help: record-triggered flow considerations
- Salesforce Help: Is Changed and new records
GAT Solutions is an independent Salesforce consultancy. Salesforce and AppExchange are trademarks of Salesforce, Inc., and Stripe is a trademark of Stripe, Inc.