Salesforce CPQ sync

TrueUpp reads usage terms from CPQ with a SOQL query you write and a field map onto its segment shape. Your Salesforce administrator needs about thirty minutes; try it in a sandbox first.

1. Create a certificate

openssl req -x509 -newkey rsa:2048 -keyout trueupp_sf.key -out trueupp_sf.crt \
  -days 730 -nodes -subj "/CN=TrueUpp"

2. Create the connected app

1. In Setup › App Manager › New Connected App (or an External Client App), name it "TrueUpp" and enable OAuth settings.
2. Set any callback URL (for example https://login.salesforce.com/services/oauth2/success); the JWT flow doesn't use it.
3. Tick Use digital signatures and upload trueupp_sf.crt.
4. Add the scopes Manage user data via APIs (api) and Perform requests at any time (refresh_token, offline_access), and save.
5. Open Manage › Edit Policies, set Permitted Users to Admin approved users are pre-authorized, then add the integration user's profile or permission set.
6. Copy the consumer key from Manage Consumer Details.

3. Write the query and field map

The field names depend on how your CPQ is set up; this example uses common ones and two custom fields (Included_Credits__c and Overage_Rate__c). Change those and the filter to match your setup:

SELECT Id, SBQQ__Account__r.AccountNumber, SBQQ__StartDate__c, SBQQ__EndDate__c,
       Included_Credits__c, Overage_Rate__c
FROM SBQQ__Subscription__c
WHERE SBQQ__Product__r.Family = 'Usage'

Map account ID, start, end, included units and overage rate (required); label, true-up months, rollover cap, cap basis, rollover periods, amendment ID, metric and record ID are optional. Dot paths like SBQQ__Account__r.AccountNumber work. The account ID must match the account ID on TrueUpp contracts.

4. Connect and preview

In Settings › Connections › Salesforce CPQ, enter the login URL (https://test.salesforce.com for a sandbox), the consumer key, the integration username, the query, the field map and all of trueupp_sf.key. Before saving, TrueUpp runs the query on up to 20 records and checks they map; it won't save a setup where none do, and the message names the first field that failed.

How the sync behaves

• A new account becomes a new contract; consecutive records become segments.
• A record that starts inside the current segment is an amendment and is added as a new segment. Earlier periods are never recalculated.
• If CPQ shows different terms for a segment TrueUpp already has, nothing is changed: a Review exception asks you to amend the contract if CPQ is right.
• Optionally, TrueUpp writes remaining credits and the next rollover expiry to fields you name on the returned record. Those fields are display only; TrueUpp stays the source of truth for billing.

Sync runs daily, or on demand.