Salesforce

Integrate Fours with Salesforce to create private offers, manage contracts, and co-sell across AWS, Azure & GCP Marketplaces directly from your CRM.

Overview

This guide walks you through integrating Salesforce with Fours, enabling your sales and business teams to:

• Create marketplace offers directly from Salesforce opportunities
• Manage co-sell referrals within your existing CRM workflow
• Sync opportunity data between Salesforce and marketplace platforms
• Streamline collaboration between sales teams and marketplace operations

How the integration works

When something fails

• A failing object type does not stop the rest. Record writes are sent with allOrNone: false in batches of 200, so a rejected record does not roll back the batch — per-record outcomes are collected and the run moves on to the next object type.
• The 4-hourly backfill does not retry itself. It is deliberately single-attempt: a re-run part-way through could duplicate records that have no external ID to upsert against. The next scheduled pass picks the work up instead.
• Enrichment activities do retry — 2 to 3 attempts with exponential backoff starting at 1 second.
• An expired session is recovered silently. A 401 INVALID_SESSION_ID makes Fours reload the stored credential and retry once. A 400 invalid_grant means the refresh token is no longer usable: Fours stops, flags the integration as needing re-authorization, and notifies you rather than retrying into a lockout.
• Fields that do not exist in your org are skipped, not failed. If a mapped field is missing from your Salesforce schema, that field is dropped from the write and logged; the rest of the record still syncs.

Prerequisites

• A Salesforce Administrator account
• A Fours organization account and API Key (see Authenticate with the Fours API)
• Installation link for the Salesforce package (Production or Sandbox)
• A current version of the Fours managed package, if you want the fields described under Package Fields and Sync Behavior. Those fields ship with the package, so an org on an older version will not receive that data until it upgrades.

Installation

Install the Salesforce Package

Install the Fours package from the AppExchange:

1. Click Get it Now

   

2. Log in with your Salesforce Admin account
3. Choose Install in Production (or Sandbox)
4. Select Install for Admins Only / All Users / Specific Profiles
5. Click Install

Set Up Integration User

To connect Fours with Salesforce, you need a dedicated Integration User account. This user will authenticate via OAuth 2.0 Web Server Flow and allow Fours to communicate with your Salesforce org using REST APIs.

Creating a dedicated Integration User ensures:

• Secure and isolated access for API calls
• Easier troubleshooting and monitoring
• No dependency on personal user accounts

Choose a License Type

When creating the Integration User, select one of the following license types:

Create the Integration User

1. In Salesforce Setup, go to Users → New User.

   

2. Enter a valid email address (required for activation).
3. Assign one of the licenses listed above.
4. For Salesforce Integration License, assign the Salesforce API Only System Integrations profile.
5. Save and activate the user.

Assign Permission Sets

After creating the user, assign the necessary permission sets depending on the license type. For more details, see Assign Fours permission sets to your team.

If using Salesforce License:

• Assign the Suger Integrator permission set.

• Create an additional permission set granting Read and View All access on:

  • Account
  • Contact
  • Opportunity
  • Any other objects/fields required in your field mapping

  If you are using standard Quote, grant Read access to Product2, Pricebook2, and Quote. The combination of these three permissions also grants access to QuoteLineItem (no separate permission is required).

If using Salesforce Integration License:

• Assign the Suger Integrator (Salesforce Integration License) permission set.
• Create a new permission set (with Salesforce API Integration as the license type) granting Read and View All access on:
  • Account
  • Contact
  • Opportunity
  • Any other objects/fields required in your field mapping
• When creating this permission set, be sure to select Salesforce API Integration as the license. Note that it is Salesforce API Integration, NOT Salesforce Integration.

At this point, your Integration User is ready. You can now proceed to connect Salesforce and Fours via OAuth in the next step.

Configuration

To enable two-way communication, you need to:

1. Allow Salesforce → Fours (enter Organization ID and API Key in Salesforce).
2. Allow Fours → Salesforce (authorize access via OAuth).

Configure Salesforce to Access Fours

This step configures Salesforce so it can call Fours APIs.

1. Get your Organization ID and API Key

   • Organization ID: found in Fours Console → Settings → Organization & Users

     

   • API Key: generate in Fours Console → Settings → API Client
     • Follow the instructions at API Client

2. Open Suger app in Salesforce

   • In Salesforce, search for Suger under Apps and open it.

     

3. Enter settings in Salesforce

   • Go to Settings inside the Suger app.

   • Fill in:

     • Organization ID
     • API Endpoint: https://api.suger.cloud
     • API Key (check no trailing spaces)

   • Click Save.

     

Configure Fours to Access Salesforce

This step configures Fours Console to connect to Salesforce using the Integration User.

1. Go to Integrations in Fours Console

   • Navigate to Settings → Integrations → Salesforce.
   • Click Connect Now.

     

2. Select Environment

   • Enter your Salesforce Subdomain (e.g., acme.my.salesforce.com).
   • Check Sandbox if you are connecting to a sandbox org.

     

   • Click Create

Find your Salesforce Subdomain in Salesforce Setup → Company Settings → My Domain.

3. Verify the connection

   • Click Verify.

     

Use Your Own External Client App

By default, Fours connects using its own managed OAuth app — you only need to enter your subdomain and click Create. If you prefer to connect with your own Salesforce External Client App (ECA) instead, toggle Custom External Client App on the connect form and enter its Consumer Key and Consumer Secret.

First, create the External Client App in Salesforce (Setup → External Client App Manager → New External Client App) and configure its OAuth settings:

• Callback URL: https://api.suger.cloud/public/integration/salesforce/oauthCallback
• OAuth scopes:
  • Manage user data via APIs (api)
  • Perform requests at any time (refresh_token, offline_access) — required. Without it Salesforce returns no refresh token and Fours rejects the connection (otherwise it would stop working once the first access token expires).
  • Access the identity URL service (id) — optional; only needed if you enable Change Data Capture (real-time sync), which uses your Salesforce org ID. Core sync, offers, and co-sell work without it.
• Under Flow Enablement, enable Authorization Code and Credentials Flow (the flow Fours uses).
• Under Security, enable Require Proof Key for Code Exchange (PKCE).
• Leave Enforce Refresh Token IP Allowlist disabled, unless you add Fours’ egress IPs to the allowlist (otherwise token refresh will fail).

External Client Apps have no “valid until revoked” setting (that’s a classic Connected App option). There is no fixed refresh-token expiry to configure; the only expiry is the optional Limit Idle Refresh Token TTL to 30 Days, which never triggers for an active integration that refreshes regularly.

Then enter the Consumer Key (as Client ID) and Consumer Secret on the Fours connect form and click Create.

Choose What Backfills to Salesforce

The scheduled backfill (every 4 hours) copies Fours objects into the Fours custom objects in your Salesforce org. You choose which objects it copies, and how far back it reaches, on the Salesforce integration’s Backfill To Salesforce Configuration tab. Editing the integration requires the Admin role.

1. Go to Integrations in Fours Console, open the ⋯ menu on the Salesforce card, and click Edit.
2. Open the Backfill To Salesforce Configuration tab.
3. For each object, turn Sync on or off. With Sync on, choose All to backfill every record, or choose Days Back and enter a number of days from 1 to 365 to backfill only recent records.
4. Click Save.

A new Salesforce integration starts with these settings:

User Interface Setup

Enable Fours Widget on Opportunity Pages

Add the Suger Opportunity Quick Panel component to enable Fours features directly on opportunity records. For more details, see Add Fours widgets and buttons to Salesforce pages.

1. Open Salesforce Setup → Object Manager → Opportunity → Lightning Record Pages.
2. Edit the Opportunity Record Page.
3. In the Components panel, search for Suger.

   

4. Drag and drop Suger Opportunity Quick Panel onto the page layout.

   

5. Save and activate the page.

When configured, users will see New Offer and Co-sell buttons on Opportunity records.

Assign User Permissions

Your team will only see the correct Fours buttons if they are assigned the right Permission Set. Fours provides three permission sets:

Example: If a user is assigned Suger User – Cosell, they will only see the Co-sell button in the Fours Widget.

Custom Permissions

Under the hood, button visibility is controlled by the following Custom Permissions (under the Suger namespace). For more details, see Fours custom permissions in Salesforce.

• Create Offer
• Create Referral

Co-sell Field Mapping

Link Salesforce fields (such as Amount or Close Date) to partner fields (such as Expected Revenue or Target Close Date) so co-sell referrals carry the right values. For more details, see Configure Co-Sell Settings for Salesforce.

Authentication & Security

Fours connects to your Salesforce org via the OAuth 2.0 Authorization Code flow with PKCE, with Refresh Token Rotation, 30-day idle TTL, and IP allowlist enforced at the External Client App level.

See Salesforce App → Authentication & Security for the full reference — OAuth flow, token storage, required admin policy settings, revocation, and transport security.

The Salesforce card in Settings → Integrations also reports when its stored credential has stopped working — for example after a refresh token is revoked in Salesforce, or the connection sits idle past its TTL. See Connection health.

Reconnect the integration

When the Salesforce connection stops working — for example after its refresh token is revoked, or after you tighten OAuth policy in Salesforce — reconnect it instead of deleting it. Reconnect runs Salesforce OAuth again for the existing integration and replaces only its stored credential; the offer-lookup map, backfill configuration, approvals, and enrichment settings are kept.

1. Go to Integrations in Fours Console, open the ⋯ menu on the verified Salesforce card, and click Reconnect.
2. The confirmation dialog names the Salesforce user the integration is connected as. Plan to sign in as that user — otherwise Salesforce may simply reuse whichever session your browser already holds.
3. Leave Change the connected Salesforce user unchecked — it starts unchecked every time — unless you mean to move the integration to a different Salesforce user (see below). Click Reconnect.
4. Salesforce opens in a new window and asks you to sign in again, with the connected username already filled in. Sign in and approve access. The window closes and the console confirms Salesforce reconnected successfully.

If you sign in as a different Salesforce user

Fours compares the account you signed in with against the one the integration is connected as, ignoring letter case and surrounding spaces. If they differ and Change the connected Salesforce user was not checked, Fours cancels the reconnect before touching anything — the integration keeps running as the original user, on its existing credential. The error names both accounts and stays on screen until you dismiss it:

Reconnect cancelled: this integration is connected as {connected user}, but you signed in as {your user}. Sign out of Salesforce (or use a private window) and reconnect as {connected user}. To intentionally run the integration as {your user}, re-run Reconnect and check “Change the connected Salesforce user”.

To move the integration to another Salesforce user on purpose — a new dedicated integration user, or because a sandbox refresh or a domain change renamed the original — run Reconnect again with Change the connected Salesforce user checked. Fours then does not pre-fill the connected username, so you can sign in with the new account. Record ownership and permissions follow the new user.

CRM Enrichment

Automatically populate Salesforce records with intelligence signals from Fours (engagement scores and marketplace metrics across AWS, Azure, GCP).

See Salesforce App → CRM Enrichment for the full configuration guide — custom field setup, SOQL targeting, refresh-cycle controls, and sync progress tracking.

Package Fields and Sync Behavior

The fields below ship with the Fours managed package. If your Salesforce org is on an older package version they do not exist in your schema yet — and because Fours skips fields that are missing rather than failing the record, the rest of your sync keeps working while these values silently never appear.

Upgrading the Fours managed package is therefore a prerequisite for the data in this section. See Install the Salesforce App for the upgrade path.

Recently added fields

All field names below carry the Suger__ namespace in your org (for example Suger__Entitlement__c.Suger__AWS_License_ARN__c).

AWS Partner Central leads

Fours now backfills AWS Partner Central leads into their own object, Suger__Lead__c, on the same schedule as the other objects. A lead is the pre-opportunity signal AWS shares with you; keeping it in Salesforce means you can route, report on, and follow up leads in the same place as the referrals they become.

Each record carries:

Partner contact associations

The partner contacts Fours backfills as Contact__c records — the AWS, Azure, GCP, or Fours partner sellers mapped to your accounts — now also get one row per association, in two objects that ship with the managed package, so you can report on which partner sellers are tied to which accounts and opportunities.

Both objects carry the same columns, so one report shape works for either:

Reports. The package adds the report type Accounts with Suger Partner Contacts and, built on it, the ready-made [Suger] Partner Contacts by Account report in the Suger Reports folder. Group or filter on Link Source to separate confirmed referral activity from inferred domain matches. The report types Opportunities with Suger Partner Contacts, Suger Partner Contact Accounts, and Suger Partner Contact Opportunities, and the [Suger] Partner Contacts by Opportunity report built on the first, are no longer installed with the package: every packaged custom report type counts against your org’s custom report type limit, and orgs already at that limit could not upgrade. An org that installed them earlier keeps them; new installs do not get them. See Partner Contact Report Types.

How the rows stay current. The Contact backfill writes these rows right after the contacts themselves, so they follow the Contact setting under Choose What Backfills to Salesforce. When an association ends, its row is deleted on a later pass, so a contact is not reported against an opportunity it no longer relates to. When Fours cannot confirm an association — for example because the Integration User can no longer see the Account or Opportunity — it keeps the row rather than delete it. Rows for a contact that is no longer one of Fours’ partner contacts are removed once no pass has confirmed them for 30 days. Fours manages these rows, so hand edits are overwritten on the next pass.

Sync behavior notes

Funding data follows the FundingRequest backfill. The funding fields above reach Salesforce only while the FundingRequest backfill is on, and it is off by default — see Choose What Backfills to Salesforce. AWS Annual Run Rate is now also filled for ISV Workload Migration requests.

Entitlement name and dates now follow the latest term. Entitlement__c’s Name, Start Date and Creation Date reflect the latest entitlement term and its linked offer, rather than the original one the entitlement was created from. This fixes renewed entitlements showing stale values.

Products not yet listed on a marketplace are skipped, not fatal. A product with no external ID (because it has not been listed on a marketplace yet) is now skipped during backfill. Previously it aborted the whole backfill with a required-field error, so a single unlisted product could block every other object from syncing.

Partner-to-partner co-sell referrals are included in the periodic backfill. Fours partner-to-partner co-sell referrals now sync on the regular 4-hourly backfill, not only when a single record is synced on demand. If you were re-syncing these by hand, you no longer need to.

Auto-share criteria can filter on a child object. Auto-share criteria that reach across to a related object — for example narrowing to opportunities that contain a particular Opportunity Product — now work. Previously a criteria of that shape failed the whole auto-share run, so a single cross-object condition stopped every opportunity from being shared, not just the ones it described.

Nothing about how you write criteria changes, and a criteria that already worked keeps behaving identically. See Auto-Share Referrals for the Builder, the Advanced (SOQL) tab, and Preview matches.

AWS revenue-record payment terms follow the accepted AWS term. On AWS revenue records, RevenueRecord__c.Payment_Terms__c now carries the net payment term accepted on the AWS agreement whenever one is known — even when the invoice date or payment due date is missing, or the gap between them differs from that term. Records without an accepted term, and all non-AWS records, still derive Net N from the invoice date to the payment due date. A value synced earlier can change when the record next syncs. Revenue records reach Salesforce only while RevenueRecord sync is on — see Choose What Backfills to Salesforce.

GCP dates now match the Google Cloud Marketplace day. The Start Date of a GCP Entitlement__c, and the Contract Start Time and Contract End Time Fours derives for GCP Offer__c records synced from Google Cloud Marketplace, now use the calendar day the GCP portal shows (US Pacific time) instead of the UTC date. Before, an offer accepted late in the Pacific day could show the following day in Salesforce.

• When Fours corrects an active GCP entitlement’s end date to match its offer’s term, the new End Date is pushed to Salesforce right away instead of waiting for the next scheduled backfill.
• A GCP offer that starts on acceptance and has not been accepted yet now shows a Contract End Time with a blank Contract Start Time. That end reflects the term Google reports for the pending offer and can change once the customer accepts.

How Fours matches contacts

Fours identifies partner contacts in Salesforce by Suger__Contact_ID__c. A second external ID, Suger__Contact_ID_CS__c (“Contact ID (Case-Sensitive)”), is also populated with the same value on every sync, but it is not used for matching — it is being staged for a future migration. Orgs on an older Fours package that lacks Suger__Contact_ID_CS__c sync normally; the field is optional and its absence does not block contact sync.

Fours AI Tools

Fours AI uses a middleware strategy — wrapping the Salesforce REST API directly.

Org-level only: Salesforce tools use the org-level integration credentials.

Troubleshooting

Frequently Asked Questions

How long does the integration take? A standard setup typically takes 10–15 minutes.

What authentication method does Fours use to connect with Salesforce? OAuth 2.0 Authorization Code flow with PKCE, through a dedicated Integration User. Fours never requires or stores a username and password.

Can we create Agreement-Based Offers (ABO) from Salesforce? Yes, directly within the Salesforce widget.

Will ACE referrals show up in Salesforce? Yes. Referrals submitted from the Salesforce widget link automatically to the Opportunity. Referrals submitted from the Fours Console can be linked manually by adding the connected Opportunity ID. Referrals submitted directly from ACE can also be found and linked manually in Salesforce.

Does Fours edit our native objects, like Opportunities or Accounts? No. The Fours managed package only creates custom objects it manages (Offers, Referrals, Entitlements, Contacts, etc.). Fours only edits native objects if explicitly given write access for a specific purpose, such as writing engagement scores to an Account or offer details back to an Opportunity.

How do I map standard, custom, or CPQ fields to Fours private offer fields? Configure field mappings in the Fours Console under your Salesforce Integration settings. Fours supports one-to-one mappings, picklist value mappings, and an Expression Mode (SOQL) for conditional logic. If your mapping involves CPQ quotes (SBQQ__Quote__c), the Integration User needs both a standard Salesforce License and a CPQ license.

Why can’t Fours see or sync certain opportunities? Fours’ visibility is entirely determined by the Integration User’s sharing rules and permissions. Confirm the Integration User’s permission set grants Read and View All access to Account, Contact, and Opportunity, plus any mapped custom fields.

How do I set up separate Sandbox and Production environments? Create separate integrations for each. In Fours Console, create a dedicated testing organization, then check the Sandbox box and enter your Sandbox subdomain when configuring that integration.

Can I build reports combining Salesforce Opportunities with Fours offer and referral data? Yes. Fours syncs marketplace data into custom objects like Offer__c, Referral__c, and Entitlement__c. Create Custom Report Types (for example, “Opportunities with Fours Offers”) to report on this data. Due to standard Salesforce reporting limits, Referrals and Entitlements can’t be joined in a single report — use two separate reports.

How do I protect standard fields, like Stage Name, from being overwritten during sync? Use Salesforce validation rules to restrict edits on the field, or map the incoming data to a read-only custom field instead.

Removing the Integration

To completely remove the Salesforce integration:

From Fours Console

1. Navigate to Fours Console → Settings → Integrations → Salesforce
2. Click the 🗑️ Delete button
3. This removes stored credentials from Fours

From Salesforce

1. Go to Setup → Connected Apps OAuth Usage
2. Locate the Suger Connected App
3. Click the User Count link
4. Click Revoke (specific user) or Revoke All (all users)