A self-serve SaaS company gets signups, and Lead Status was built for sales calls. It says whether someone was contacted or qualified. It cannot say whether a person finished setup, used the product, started a trial or paid, so reports guess and automations fire on the wrong people.
We drew the fields and rules from one build for a self-serve product that created one Lead per confirmed user and billed through Stripe. For ad attribution, pair it with how we tie every ad lead to a Salesforce Campaign.
What you need before you start
- An admin who can create fields, validation rules and flows, and a sandbox.
- An integration user for the product, with edit rights on the lifecycle fields.
- Every status your billing system can return.
- One agreed sentence that defines activation in your product.
Signed Up
Account created, email confirmed.
Set Up
Required setup done. In one build, the first app connected.
Activated
The product did its core job on the person's own data.
Trialing
Billing reports a trial. Nothing charged yet.
Customer
Billing reports Active. Convert the Lead here, once.
Gone Quiet and Canceled sit beside the line, set by activity and billing.
Step 1: Define each stage so a report can test it
Write each stage as a fact the product already records, so two people cannot disagree about it.
| Stage | A Lead is here when | Proven by |
|---|---|---|
| Signed Up | The account exists and the email is confirmed | Signup At |
| Set Up | Required setup is complete | Set Up At |
| Activated | The first successful core action on real data | Activated At |
| Trialing | Billing reports a trial | Subscription Status Trialing |
| Customer | Billing reports an active paid plan | Subscription Status Active, and Past Due if you count it (below) |
| Gone Quiet | Activated, unpaid, and no qualifying action for a set number of days | Last Active At |
| Canceled | The subscription has ended | Subscription Status Canceled or Expired |
Activated needs the most care. Pick one action that means the product did its job, and count its first success only. In one build, we counted the first successful read of real data through a connection, and excluded logins, authorization screens, listing steps, health checks, failed calls and writes.
A listing step shows someone looked around, a failure delivered nothing, and a login shows only that the door opened. Count them and the rate rises while nobody got a result. When that build once counted a listing step, its activated email reached people who had only looked around. For Gone Quiet, it emailed at 7 and 30 days after the last qualifying action. Test your own number.
Past Due is your decision. Stripe marks a subscription past due when a renewal payment fails, keeps invoicing, and retries on your retry settings. Count Past Due as Customer, and one failed card does not pull a paying person out of Customer, but Customer then includes people whose payment is failing. Count it with Canceled, and Customer holds only subscriptions in good standing, but a retry that succeeds days later moves the Lead back, and stage emails can fire twice.
Step 2: Create the fields and keep Lead Status for sales
Lead Status stays the sales process. Salesforce marks one or more of its values as converted, and reps keep using it as they do now. A Lead can be Activated while Lead Status still says New, because nobody has called yet.
| Field | Type | Holds |
|---|---|---|
Lifecycle_Stage__c | Picklist, restricted | The seven stages |
Subscription_Status__c | Picklist, restricted | None, Trialing, Active, Past Due, Canceled, Expired |
Signup_At__c, Set_Up_At__c, Activated_At__c | Date/Time | One per milestone, set once |
Last_Active_At__c | Date/Time | The newest qualifying action |
Product_User_Id__c | Text, External ID, Unique | The product's user id |
Billing_Customer_Id__c | Text | Where to find the person in billing |
| UTM fields, click ids, landing page, referrer, original source | Text | How the person found you |
On both picklists, select Restrict picklist to the values defined in the value set, which stops the API adding stray values. Payment dates and amounts stay in billing. Lock the External Id once set, as we did in one build, because a changed id cuts the Lead off from its person.
AND( ISCHANGED(Product_User_Id__c), NOT(ISBLANK(PRIORVALUE(Product_User_Id__c))))Step 3: Decide who writes each field
Every lifecycle field has one writer: the product, through the API, as the integration user. People own Lead Status, the owner and the unqualified reason. Field-level security makes the lifecycle fields read only for everyone else.
The product upserts each person on Product_User_Id__c. Salesforce creates a Lead when no record has the id, updates the one that does, and refuses when it matches more than one, so a retry lands on the same Lead. In one build, we also held the product to four rules:
- Never send a blank. A missing value leaves the field as it was.
- Set each milestone timestamp once and never clear it.
- Write name and original source at create, and never overwrite them.
- Before creating a Lead, stamp the id on an unconverted Lead with the same email and no id. The duplicate leads guide covers matching.
The product works the stage out from those set-once facts and writes the first match, in this order: Active is Customer, Past Due goes where you put it in step 1, Canceled or Expired is Canceled, Trialing is Trialing, activated and quiet past your limit is Gone Quiet, then Activated, Set Up and Signed Up from the timestamps. A retry, a replay or a late event gives the same answer, so stages move only forward. Name this writer before you create the field, because a stage nothing writes goes stale.
Step 4: Convert only on an active subscription
A Lead reaches Customer when billing says Active. Stripe moves a trialing subscription to active when the customer makes the first payment, so a trial has not paid. Keep it at Trialing and unconverted.
Convert when Subscription Status changes to Active. Conversion relates the Lead to a new or existing Account and Contact, and optionally an Opportunity, and Salesforce says you can't reverse it. The converted Lead is read only except to users with View and Edit Converted Leads, and other writes get CANNOT_UPDATE_CONVERTED_LEAD.
- Let one automation own conversion, and run it on the change to Active.
- Have the product check
IsConvertedand stop writing.ConvertedContactIdshows where the person went. - Count the Leads the first run would convert, and try that batch in a sandbox. Replayed billing events can convert many at once.
- Validation rules run during conversion only when Require Validation for Converted Leads is selected in Lead Settings.
Step 5: Require a reason to disqualify
A disqualified signup with no reason teaches you nothing. Add a text field, Unqualified_Reason__c, and this rule, with the message "Enter an Unqualified Reason before marking this Lead Unqualified."
AND( ISPICKVAL(Status, "Unqualified"), ISBLANK(TRIM(Unqualified_Reason__c)), OR(ISNEW(), ISCHANGED(Status), ISCHANGED(Unqualified_Reason__c)))The last line checks only on create or when the status or reason changes, so older Unqualified Leads stay editable. TRIM matters because Salesforce treats a field holding a space as filled. For a fixed list of reasons, use a picklist and ISBLANK(TEXT(Unqualified_Reason__c)).
Step 6: Build the reports
- Signup to activated. Add number formula fields
IF(ISBLANK(Signup_At__c), 0, 1)and the same forActivated_At__c. Group a Lead report by signup month and add a Percent summary formula, activated sum over signed-up sum, the shape of Salesforce's ownWON:SUM/CLOSED:SUMexample. - Time to activate.
Activated_At__c - Signup_At__creturns days as a decimal. Average it by signup month. - Activated to paid. Conversion happens only on an active subscription, so Converted means billing reported Active at least once. Filter to activated Leads and group by the Converted field.
- By campaign. Group any of these by UTM Campaign, or report on Campaign Members. In one build, a flow added each new Lead, once, to the active Campaign whose campaign key matched.
Step 7: Check for the four ways it breaks
One bad field name rejects the whole write. A field that exists in your sandbox and not in production returns INVALID_FIELD, and the valid fields in that record are not saved either. A value missing from a restricted picklist fails with INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST. Check the product's field list against production before each release, and map every billing status, including Stripe's unpaid, incomplete and paused.
Stages move backward. An older value, a blank or a hand edit lands on the field. Step 3 closes all three.
A second customer flag disagrees with billing. A checkbox someone ticks drifts from what billing says. Customer comes from Subscription Status alone, and Subscription Status from billing alone.
Access checks live in the CRM. The product decides access from its own database and billing, and Salesforce gets a copy. Salesforce caps an org's API requests per 24 hours, and Stripe says you can safely give a trialing customer the product, so a check that waited for Customer would lock trial users out.
Every setting on one page
| Setting | Where it lives | Value in this guide |
|---|---|---|
| Lifecycle fields | Lead, Fields | The table in step 2, written by the product |
| Product_User_Id_Locked | Lead, Validation Rules | Blocks changes once set |
| Unqualified_Reason_Required | Lead, Validation Rules | Reason required for Unqualified |
| Field-level security | Permission sets | Lifecycle fields read only for people |
| Conversion | One automation | On Subscription Status changing to Active |
When the numbers look wrong
| What you see | Likely cause | What to check |
|---|---|---|
| The upsert returns a 300 error | Two Leads share one product id | Unique on the External Id |
| Two Leads for one person | A form Lead existed before the signup | Email matching before the first upsert |
CANNOT_UPDATE_CONVERTED_LEAD | The product writes to a converted Lead | The IsConverted check |
| Activation rate looks too high | Discovery or setup is counted | The activation definition |
Before you turn the sync on for every user
Backfilling every user is a release, so answer three questions before you run it.
- Which flows fire on the first sync? A flow that emails on a stage change fires for every backfilled Lead whose stage changes. Load the history before the flow is live, or decide that first send on purpose.
- What happens to existing Leads? Form fills and old imports need the product id stamped on them, or people get two Leads.
- How many Leads convert on day one? Count them in a sandbox, as in step 4.
Frequently asked questions
What is the difference between Lead Status and a lifecycle stage?
Lead Status tracks the sales conversation. A lifecycle stage tracks what the person did in the product and what billing says. Keep them in separate fields with different writers.
Should a free trial count as a customer in Salesforce?
No. In Stripe, a trialing subscription moves to active when the customer makes the first payment. Until then, keep the Lead at Trialing and unconverted.
Can you undo a lead conversion in Salesforce?
No. Salesforce Help says you can't reverse a lead conversion. The converted Lead is read only, and only users with the View and Edit Converted Leads permission can update it.
What should count as activation in a SaaS product?
The first successful use of the product's core job on the person's own data. Logins, authorization screens, listing steps and failed attempts come before any result, so they do not count.
Can my app check Salesforce to decide what a user can access?
Keep access in the product's own database and billing system, and send Salesforce a copy. Salesforce caps an org's API requests per 24 hours.
Official references
- Salesforce Help: convert qualified leads
- Object Reference: Lead and LeadStatus
- REST API: upsert using an External ID
- Object Reference: External ID on custom fields
- SOAP API: status codes
- Salesforce Help: validation rules and considerations
- Salesforce Help: PRIORVALUE and ISBLANK
- Salesforce Help: Date/Time values in formulas
- Trailhead: restricted picklists, field-level security and summary formulas
- Object Reference: CampaignMember
- Salesforce Developers: API request limits
- Stripe Docs: subscription statuses
GAT Solutions is an independent Salesforce consultancy. Salesforce and Trailhead are trademarks of Salesforce, Inc., and Stripe is a trademark of Stripe, Inc.