Opportunity Creation and Quote Sync
How opportunity linkage works across Salesforce and quote workflows, what fields matter, when primary quote is required, and why certain sync actions get blocked.
Overview
Opportunity sync in MonetizeNow is built around pairing one MN Opportunity with one Salesforce Opportunity and keeping that pairing stable as quotes move through the pipeline. Linkage, creation, and outbound updates each follow separate rules. This doc covers all three.
Which MN Opportunity maps to which Salesforce Opportunity, tracked through IDs and association records.
Which quote is designated as primary for an opportunity. Changing it after finalization is blocked, and certain linking flows depend on it being set correctly in Salesforce.
Whether an action originated in Salesforce or in MonetizeNow. Both paths exist and both have their own rules.
Two Directions. One Relationship.
Sync runs both ways, but each direction has its own logic and prerequisites.
Flow A: Salesforce → MonetizeNow
- SFDC Opportunity: starting point
- Check for link:
monetize__Id__c? - Check primary quote: MN Quote ref?
- Link or Create: MN Opportunity
Key rule: If monetize__Id__c is already populated on a SFDC Opportunity, MonetizeNow treats it as already linked and won't relink through this path. If no ID is found, it looks for a primary quote reference to resolve which opportunity to link.
Flow B: MonetizeNow → Salesforce
- MN Opportunity: already linked
- Locate SFDC record: association or
customId - Update SFDC Opp: link + primary quote
Key rule: If a Salesforce Opportunity can't be located (no stored association, no customId), sync is skipped. MonetizeNow requires a confirmed identifier before writing back to Salesforce.
Fields That Control Linkage Behavior
These are the fields on each side that determine how opportunities are linked and synced.
Salesforce Fields
| Field | What it does |
|---|---|
monetize__Id__c | Populated by MonetizeNow once an opportunity is linked. Its presence signals that a link already exists. |
monetize__PrimaryQuote__c | Reference to the MN Quote used to resolve which opportunity to link when no link exists yet |
| Name / Account | Carried into MonetizeNow when a new opportunity is created from a Salesforce-initiated quote flow |
MonetizeNow Fields
| Field | What it does |
|---|---|
| MN Opportunity ID | Primary identifier for an opportunity in MonetizeNow |
| MN Quote ID | Quote designated as primary for this opportunity |
| MN↔SFDC association | Stored internally once a link is confirmed. MonetizeNow uses this to locate the right Salesforce record for all subsequent syncs. |
How Outbound Resolution Works
When pushing updates to Salesforce, MonetizeNow checks in this order.
| # | Check | Result |
|---|---|---|
| 1 | Stored association from an earlier sync found? | ✅ Use it. Update SFDC. |
| 2 | No stored association, but a Salesforce Opportunity was referenced when this MN Opportunity was created? | ⚠️ Use that reference as fallback. |
| 3 | No link of any kind found? | ❌ Sync skipped. No SFDC update. |
Six Things Worth Knowing
Core behaviors before going live.
- One-to-one pairing. Each MN Opportunity maps to exactly one Salesforce Opportunity. If a link already exists and something tries to create a conflicting one, MonetizeNow returns an error.
- Link is established once, reused after. MonetizeNow stores the Salesforce association after initial linkage and uses it for all subsequent syncs. No manual configuration is required to maintain it.
- Primary quote is structural. In certain linking flows, a valid MN Quote reference in Salesforce is required to resolve which opportunity to link.
- Account context first. Opportunity creation depends on account linkage being in place. Without it, downstream behavior becomes unreliable.
- Unresolvable = skip. If MonetizeNow can't locate the linked Salesforce Opportunity, it skips the outbound update rather than write to an unverified record.
- Conflicts return errors. Attempting to link an already-associated opportunity to a different SFDC record throws a conflict error. The existing association has to be resolved first.
Four Operational Flows
Scenarios your team will hit most often, with what happens at each step.
Flow A: Link an existing SFDC Opportunity via primary quote
- SFDC Opportunity is received. MonetizeNow checks whether
monetize__Id__cis already populated on the incoming record. - No existing MN Opportunity ID found. MonetizeNow reads
monetize__PrimaryQuote__con the SFDC Opportunity to find a valid MN Quote reference. - Quote resolves the opportunity. The MN Opportunity linked to that quote is identified. MonetizeNow checks for conflicting associations before establishing the link.
- Association record is created. Internal MN↔SFDC pairing is stored. Future outbound syncs reference this record first.
Prerequisite: SFDC Opportunity must reference a valid, accessible MN Quote in monetize__PrimaryQuote__c. Without it, MonetizeNow has no way to determine which opportunity to link.
Flow B: Create a new opportunity from Salesforce during quote initiation
- Quote creation is initiated from Salesforce. SFDC Opportunity data is sent to MonetizeNow to initialize a quote flow.
- Account is resolved. SFDC Account on that Opportunity is matched to the corresponding MonetizeNow Account. Account linkage must already be in place.
- New opportunity is created. MonetizeNow creates the opportunity using the Salesforce Opportunity name and the matched account. The Salesforce link is stored internally for future syncs. No primary quote is set yet.
- Quote is created and field mappings apply. Field values from SFDC Opportunity populate the new MN Quote. Opportunity/quote chain is live.
Remember: Creating an opportunity from Salesforce requires both a matched account and a valid SFDC Opportunity. If account linkage is missing, the flow will fail before the opportunity is created.
Flow C: Update primary quote on an already-linked opportunity
- Opportunity already has a SFDC link. Association record exists and is confirmed as linked.
- New primary quote is validated. MonetizeNow checks that the quote/opportunity combination is valid and neither entity is in a finalized state.
- Primary quote is updated. New quote reference is stored. If SFDC Opportunity is locatable, this change is also reflected outbound.
Key constraint: Once the quote or opportunity reaches a finalized state, the primary quote reference locks. Plan primary quote designation before that point.
Flow D: Push an opportunity update back to Salesforce
- Outbound update is triggered. A change on an MN Opportunity — link established, primary quote updated — needs to be reflected in Salesforce.
- Salesforce Opportunity is located. MonetizeNow uses the stored association from when the link was first established. If that association is missing, the update is skipped.
- SFDC Opportunity is updated. Confirmed link and primary quote reference are written back to the relevant SFDC fields.
Worth knowing: If no Salesforce link can be found, the outbound update is skipped. This usually means the initial linkage between the two records was never completed.
Before You Begin
- Live Salesforce connection must exist and be authenticated.
- SFDC Account should already be linked or creatable in MonetizeNow before any opportunity flow runs.
- SFDC Opportunity must contain required fields for whichever sync path is being used.
- For primary quote-based linking, SFDC Opportunity must reference a valid, accessible MN Quote.
- For outbound sync, the opportunity must have been linked to a Salesforce Opportunity at some point. MonetizeNow uses that stored link to locate the right record.
Why Sync Actions Get Blocked or Skipped
Most "why won't this work?" moments trace back to one of these scenarios.
| Scenario | What's happening | Result |
|---|---|---|
| No Salesforce connection | No active integration | Every sync path requires a live authenticated connection |
| Opportunity already linked | monetize__Id__c is populated | MonetizeNow skips relinking through the primary quote path |
| Primary quote missing | SFDC Opp has no MN Opportunity ID and no primary quote reference | Linkage can't be resolved |
| Conflicting association | Opportunity is already tied to a different SFDC Opportunity | A new link is blocked until the existing one is resolved |
| Quote inaccessible | Referenced MN Quote is invalid or the caller lacks read access | Linking fails at the resolution step |
| Entities finalized | Quote/opportunity relationship is finalized | Primary quote updates are blocked at this stage |
| Account mapping broken | Opportunity creation from SFDC depends on a matched account | Missing account linkage breaks the flow upstream |
| Salesforce link was never established | MN Opportunity was never linked to a Salesforce Opportunity | Outbound updates have nowhere to go and are skipped |
| Invalid quote/opp combo | MonetizeNow validates the pairing before updating primary quote | Some quote/opportunity combinations are structurally invalid |
Edge Cases in Detail
What to check when users hit these in the wild.
Opportunity already has monetize__Id__c populated
monetize__Id__c populated- That SFDC Opportunity is treated as already linked
- MonetizeNow skips the primary quote linking path entirely
- To reassign a link, clear that field first
Opportunity already tied to a different SFDC record
- MonetizeNow returns a conflict error
- The existing association has to be resolved before a new link can be created
- This keeps your billing and CRM records consistent with each other
Outbound update is skipped: no Salesforce link found
- This happens when the MN Opportunity was never linked to a Salesforce record, or the initial linkage didn't complete
- MonetizeNow needs a confirmed link before writing back
- Check whether the opportunity went through a successful linking flow
Primary quote update blocked after finalization
- Once the quote or opportunity is finalized, the primary quote reference locks
- This prevents quote substitution on closed or executed deals
- Primary quote designation needs to happen before that stage
Account mapping missing on opportunity creation
- A new MN Opportunity requires both a Salesforce Opportunity and a matched MonetizeNow Account
- If the account relationship is missing, creation fails
- Confirm account linkage before triggering any quote initiation flow from SFDC
Field mapping and opportunity linking are separate
- Field mappings from a SFDC Opportunity into an MN Quote apply during quote creation and update. They control which Opportunity values populate quote fields
- Which opportunity objects get linked to each other is determined entirely by the linking flow, independent of field mapping
- Debugging one has no bearing on the other
Skipped vs. Failed
A skipped sync means MonetizeNow couldn't identify a target SFDC record and held off rather than write to an unverified one. A failed sync means something structurally blocked the action — a conflicting link, inaccessible quote, or finalized entity. Skips typically point to a configuration gap. Failures are enforced by design.
Updated 12 days ago