Your product knows who signed up, who finished setup and who has gone quiet. Salesforce usually does not. Sales works the Leads that filled in a form, customer success hears about churn when the cancellation arrives, and the people ready to buy sit in the product database where nobody in the CRM can see them.
This guide writes to Leads, and the same pattern works on Contact or Account. If your org already holds several Leads per person, start with the duplicate Leads guide.
What you need before you start
- An integration user in Salesforce that the product signs in as, and a sandbox to build in.
- A user id in the product that never changes. An email address does not qualify.
- For the live panel, a product API that returns usage per person and accepts OAuth client credentials.
Step 1: Decide what usage means
Sales needs a handful of facts: where each person is in a short journey, and when they last did something that matters. This guide uses one Lead field for each:
| Fact | Lead field | Rule |
|---|---|---|
| Product user | Product_User_Id__c, Text | The match key, set once |
| Signed up | Signup_At__c, Date/Time | Set once, never cleared |
| Set up | Setup_Completed_At__c, Date/Time | Set once, never cleared |
| First real use | Activated_At__c, Date/Time | Set once, never cleared |
| Last active | Last_Active_At__c, Date/Time | Moves forward with each qualifying use |
| Plan status | Subscription_Status__c, picklist | Mirrors billing, which stays the source of truth |
| Features in use | Features_In_Use__c, multi-select picklist | Replaced on every write, cleared when empty |
| Last sync | Last_Product_Sync_At__c, Date/Time | When the product last wrote successfully |
Define first real use strictly and write the definition into the field's description. In one build it was the first successful use of the product's core job, and logins, setup screens, health checks, failures and writes did not count.
Step 2: Choose where each fact lives
Who needs the fact, and what will they do with it?
Reports, list views, flows
Write it onto the Lead
The product upserts a few fields on an External Id, and anything in Salesforce can filter, count or route on them.
Detail that changes hourly
Read it live from the product
A Lightning web component calls the product's API through a Named Credential. Nothing is stored.
A sales and success team
Store the journey, read the detail
Funnel stages from Lead fields, with a per-person usage tab read live beside them.
A stored fact is as fresh as the last sync, and a live read costs a callout each time the page opens, so decide per fact.
Step 3: Write the facts onto the Lead
- In Setup, open Object Manager, then Lead, then Fields & Relationships. Create
Product_User_Id__cas Text with External ID and Unique checked, treating ABC and abc as duplicates. An External ID field holds ids from an outside system and can be used to upsert through the API, and Unique prevents duplicate values. - Create the other fact fields and a permission set that gives the integration user Edit on each one.
- Send changes in batches through sObject Collections upsert.
PATCH /services/data/vXX.X/composite/sobjects/Lead/Product_User_Id__c { "allOrNone": false, "records": [ { "attributes": { "type": "Lead" }, "Product_User_Id__c": "usr_8231", "Signup_At__c": "2026-11-02T14:05:00.000+0000", "Activated_At__c": "2026-11-03T09:12:00.000+0000", "Features_In_Use__c": "reports;slack_alerts" } ]}One sObject Collections upsert takes up to 200 records of one object. With allOrNone false, each record succeeds or fails on its own and the results come back in order, so the product retries only the failures. An single-record upsert on an External ID creates a record when nothing matches, updates a single match, and returns a 300 error when several match.
On the product side, one build followed five rules, and we recommend them:
- Never send a null. Leave the field out.
- Dates are set once and never cleared.
- State is replaced. The features list is sent in full every time, and an empty string clears it.
- Only new Leads get identity. Name, email, company and Lead Source go on a new Lead. An existing Lead gets the id and the facts, so reps' edits stay.
- Converted Leads are skipped.
Send only field names that exist in the target org. In one build, a single field that Production did not have was enough to reject the whole write, so new fields stayed out of the payload until they existed in every org. Deploy fields before the code that writes them. Salesforce returns a 400 for a request it cannot understand.
The product database stays the source of truth, and the sync runs one way. The product marks a user pending when a fact changes, sends the record, and clears the flag only if the row still matches what it sent. Push each change as it happens and sweep for misses on a schedule, for example every 10 minutes, then test the interval your team needs.
Step 4: Read live usage through a Named Credential
- In Setup, open Named Credentials, then External Credentials, and click New. Choose OAuth 2.0 and Client Credentials with Client Secret Flow, with the product's token URL as the Identity Provider URL. Add a principal and enter the client ID and secret. Salesforce makes it a Named Principal, one service-level sign-in for the org. Type the secret into each org; keep it out of source control.
- Create a Named Credential,
Product_API, with the product's API address as the URL and the external credential selected. Keep Generate Authorization Header on. - In a permission set, open External Credential Principal Access and enable the principal. Salesforce checks for it at run time.
- Write one Apex client that every read goes through.
public with sharing class ProductApiClient { public class ProductApiException extends Exception {} public static Object get(String path) { HttpRequest req = new HttpRequest(); req.setEndpoint('callout:Product_API' + path); req.setMethod('GET'); req.setHeader('Accept', 'application/json'); req.setTimeout(20000); HttpResponse res; try { res = new Http().send(req); } catch (CalloutException e) { throw new ProductApiException('The product did not answer. Try Refresh.'); } Integer status = res.getStatusCode(); if (status == 401 || status == 403) { throw new ProductApiException('The product refused the sign-in. ' + 'Check the Product_API credential and its permission set.'); } if (status != 200) { throw new ProductApiException('The product answered ' + status + '.'); } return JSON.deserializeUntyped(res.getBody()); }}The endpoint is callout: plus the credential's name, and Salesforce adds the sign-in. In one build we set a 20-second timeout; the default is 10 seconds and the most is 120. A 401 or 403 becomes a sentence that names what to check.
The controller checks access before it calls anything. FeatureManagement.checkPermission reads a custom permission, so a user without it gets an error even when calling the method directly. Unknown filter values fall back to a default and never reach the product.
public with sharing class ProductUsageController { private static final Set<String> WINDOWS = new Set<String>{ 'week', 'month', '30', '90' }; @TestVisible private static Boolean permissionOverride; @AuraEnabled public static Object getActivePeople(String windowKey) { Boolean allowed = permissionOverride != null ? permissionOverride : FeatureManagement.checkPermission('View_Product_Usage'); if (!allowed) throw fail('You do not have access to product usage.'); String window = WINDOWS.contains(windowKey) ? windowKey : 'week'; try { return ProductApiClient.get('/usage/people?window=' + window + '&limit=100'); } catch (ProductApiClient.ProductApiException e) { throw fail(e.getMessage()); } } private static AuraHandledException fail(String message) { AuraHandledException e = new AuraHandledException(message); e.setMessage(message); return e; }}Before returning, join each person to their Lead with one SOQL query on Product_User_Id__c, link a converted Lead to its ConvertedContactId, and return only the fields the panel shows.
In the Lightning web component's configuration file, list lightning__HomePage or lightning__RecordPage as targets. Read stored Lead facts with @wire on a cacheable=true method and call refreshApex() on Refresh. Salesforce says not to assume a cache duration. In one build the live methods were non-cacheable so Refresh returned current numbers, which meant calling them imperatively.
Give each read its own spinner and error line, so one slow answer leaves the rest of the panel working, and show the message from the AuraHandledException. Ignore an answer that arrives after the user has changed the date range.
Step 5: Decide what the panel shows
| Panel | Reads from | Question it answers |
|---|---|---|
| Active people this week, against last week | Product, live | Is usage growing? |
| Uses per person, with features and connections | Product, live | What does each account rely on? |
| Signed up, set up, first real use, paid | Lead fields | Where do people stall? |
| No setup two days after signup, or no use two days after setup | Lead fields | Whom should we call today? |
| Quiet: first real use done, nothing in seven days | Lead fields | Who might churn? |
The two-day and seven-day lines were one build's choices, so set your own. Link each name to its Lead, or to the Contact after conversion. Run weeks Monday to Sunday in one named time zone, keep the team's own accounts out of the numbers, and define each number in a short list under the panel.
Step 6: Set permissions and test the callouts
| Permission set | Assigned to | Grants |
|---|---|---|
| Product sync integration | The integration user | Edit on the fact fields |
| Product usage viewer | People who see the panel | The controller class and the View_Product_Usage custom permission |
| Product API credential | The same viewers | External Credential Principal Access |
Hide the panel from everyone else with a @salesforce/customPermission import, and keep the Apex check, since the method can still be called directly.
By default, Apex tests cannot make callouts, and a deploy needs 75% coverage, so each test sets a mock with Test.setMock.
@IsTestprivate class ProductUsageControllerTest { private class ProductApiMock implements HttpCalloutMock { public Integer status = 200; public HttpResponse respond(HttpRequest req) { HttpResponse res = new HttpResponse(); res.setStatusCode(status); res.setBody('{"people":[{"user_id":"usr_8231","uses":9}]}'); return res; } } @IsTest static void aRefusedSignInSaysWhatToCheck() { ProductUsageController.permissionOverride = true; ProductApiMock mock = new ProductApiMock(); mock.status = 401; Test.setMock(HttpCalloutMock.class, mock); try { ProductUsageController.getActivePeople('week'); Assert.fail('Expected an error'); } catch (AuraHandledException e) { Assert.isTrue(e.getMessage().contains('Product_API')); } }}The tests in that build covered each read, a refused sign-in, a user without the permission (an error and no callout), a filter value that must never be sent, and a response field that must never reach the page. Salesforce's HttpCalloutMock page has the full pattern.
Every setting on one page
| Setting | Where it lives | Value in this guide |
|---|---|---|
Product_User_Id__c | Lead, Fields & Relationships | Text, External ID, Unique, case-insensitive |
| Upsert | REST API, sObject Collections | PATCH on Lead/Product_User_Id__c, 200 per request, allOrNone false |
| External credential | Setup, Named Credentials | OAuth 2.0, Client Credentials with Client Secret |
Product_API | Setup, Named Credentials | Product API URL, Generate Authorization Header on |
| Callout timeout | ProductApiClient | 20 seconds |
View_Product_Usage | Custom Permissions | In the viewer permission set |
| Component targets | The component's configuration file | lightning__HomePage, lightning__RecordPage |
What goes wrong
| What you see | Likely cause | What to do |
|---|---|---|
| Two Leads for one customer | The sync matched on email | Match on the id. Adopt older email-only Leads once by stamping the id; in one build we took the newest and logged a warning when several matched. |
| Nothing writes after a release | A field in the request is missing in the target org | Deploy the field, then the code |
| Numbers look old | A failed sync, or a cached read | Check Last_Product_Sync_At__c, then press Refresh |
| The panel says the sign-in was refused | No secret on the principal, or no principal access | Step 4, items 1 and 3 |
| A callout fails after a save | DML ran first in the same transaction | Call out before any DML, which blocks callouts while pending |
| A busy page hits a limit | Several callouts in one method | One callout per method; Salesforce allows 100 callouts and 120 seconds of callout time per transaction |
| Access fails when Salesforce is slow | The product reads access rules from the CRM | Keep entitlement in the product database and send Salesforce a copy |
Before sales starts using it
- Agree what active means. Sales, success and product should read first real use the same way.
- Mark who owns the fields. The product writes them, so say so in each description and keep them off edit layouts.
- Choose what is sent and who sees it. In one build we sent counts, dates, feature names and outcomes, and kept request contents in the product.
- Give each signal an owner. A quiet customer needs a person and a list view.
To tie each signup to the ad that brought it, see campaign attribution in Salesforce. For how the credential parts fit, see Salesforce named credentials explained.
Frequently asked questions
Should the product write usage to Leads or to Accounts?
Write where sales already works. In one build every self-serve signup became a Lead, so the product wrote there. A converted Lead was skipped, and mapping the facts onto the Contact or Account was a separate step.
Why not match product users to Salesforce records by email?
Email changes, and several Leads can share one address. An External Id field holds the product's own user id, and marking it Unique makes Salesforce refuse a second record with the same value. Use email once, to adopt Leads that existed before the sync, then match on the id.
How current is product usage data in Salesforce?
As current as the last successful write. Send each change as it happens, retry misses on a schedule (for example every 10 minutes), and keep a Last Product Sync At field that shows when the product last wrote. A live panel reads the product each time it opens or refreshes.
Do I need Apex to get usage data into Salesforce?
Writing facts onto the Lead needs no Apex: the product calls the Salesforce REST API. Reading live usage into a Lightning panel the way this guide does needs Apex, because the callout runs from an Apex class through a Named Credential.
Can Salesforce decide what a customer is allowed to use?
Keep plan checks, credits and access rules in the product database. A copy of the plan status in Salesforce is fine for sales to read, and the product should never wait on Salesforce to decide whether a request may run.
Official references
- Salesforce REST API: upsert records using sObject Collections
- Salesforce REST API: insert or update a record using an external ID
- Salesforce REST API: status codes and error responses
- Salesforce Help: custom field attributes
- Salesforce Help: permission sets
- Salesforce Object Reference: Lead
- Salesforce Developers: named credentials glossary
- Salesforce Help: OAuth external credential with the client credentials with client secret flow
- Salesforce Help: create or edit a named credential
- Salesforce Help: enable external credential principals
- Apex Developer Guide: named credentials as callout endpoints
- Apex Developer Guide: callout limits and limitations
- Apex Developer Guide: testing HTTP callouts
- Apex Developer Guide: testing callouts with HttpCalloutMock
- Apex Reference: FeatureManagement class
- Lightning Web Components: wire Apex methods
- Lightning Web Components: call Apex methods imperatively
- Lightning Web Components: client-side caching
- Lightning Web Components: handle errors from Apex
- Lightning Web Components: check permissions
- Lightning Web Components: XML configuration file elements
GAT Solutions is an independent Salesforce consultancy. Salesforce and Lightning are trademarks of Salesforce, Inc.