Salesforce Integration

What is this page about: How to connect Salesforce to Light, what syncs automatically (opportunities, accounts, products), how quotes and contacts fit in, what falls outside standard scope, and how to troubleshoot a failed sync.

# On this page

• Integration overview
• Connecting Salesforce to Light
• Configuring opportunity sync
• What happens when an opportunity syncs
• Account and product sync
• Quotes
• What doesn't sync
• Duplicate handling
• Sync frequency and manual sync
• Monitoring and troubleshooting sync
• Custom field mapping
• Reporting and exporting synced data
• Unsyncing or reversing a record
• Related articles

Light's Salesforce integration turns a closed deal into finance-ready records automatically. When a sales rep marks an opportunity Closed Won in Salesforce, Light creates the matching contract or accounts receivable (AR) invoice, using account and product data that's already synced. Your team stops re-entering CRM data into Light by hand.

# Integration overview

Once connected, the Salesforce integration keeps four things in sync between Salesforce and Light.

• Opportunities. When an opportunity closes in Salesforce, Light creates a contract or an AR invoice from it, depending on how you've configured the workflow.
• Accounts. Salesforce accounts sync to Light as customer records.
• Products. Salesforce products, including standard price book pricing, sync to Light as product records.
• Filtering. You control which opportunities sync using a SOQL filter. By default, only Closed Won opportunities sync.

Field mapping (which Salesforce field fills which Light field) is configured in the Salesforce to Light workflow, covered below.

# Connecting Salesforce to Light

1. Open Light and go to Settings → Integrations → Salesforce.
2. Click Connect.
3. Choose your Salesforce environment: Production or Sandbox.
4. Light redirects you to Salesforce. Log in and approve the connection on Salesforce's own login screen. You never enter your Salesforce password into Light.
5. Review the permissions Light is requesting, then confirm.
6. Light confirms the connection is active.

Next, open the Salesforce to Light workflow under Settings → Workflows to configure what syncs.

# Configuring opportunity sync

The Salesforce to Light workflow controls how an opportunity becomes a contract or invoice.

1. Go to Settings → Workflows and open Salesforce to Light.

2. Set the opportunity filter. This is a SOQL filter. By default, it syncs only closed-won opportunities: IsClosed = TRUE AND IsWon = TRUE. Add conditions for stage, amount, or close date if you want a narrower filter.

3. Set the field mappings. By default, an opportunity maps to a Light contract as follows:

   • Salesforce Account → Light Customer
   • Opportunity Amount → Contract Estimated Amount
   • Opportunity Description → Contract Description
   • Opportunity Currency → Contract Currency
   • Opportunity Line Items → Contract Lines (product, quantity, discount, synced automatically for every line item on the opportunity)

4. Publish the workflow to turn on the sync.

Light validates the workflow before activating it, to catch mapping errors early.

# What happens when an opportunity syncs

When a synced opportunity matches your filter:

1. Light reads the opportunity, including its account and line items.
2. If the account doesn't already exist as a customer in Light, Light creates one from the Salesforce account.
3. Light creates a contract with the customer, estimated amount and currency, and contract lines from the opportunity.
4. You can configure the workflow to create an AR invoice instead of (or in addition to) a contract. A negative amount creates a customer credit instead.
5. The record lands in Light for your review before it posts to the general ledger.

Have finance review the first several synced records to confirm the mapping is right, then turn on auto-posting once you're confident in it.

# Account and product sync

Beyond opportunities, the same workflow syncs Salesforce accounts and products to Light.

Accounts, by default:

• Account Name → Customer Name
• Account Website → Customer Domain
• Account Description → Customer Description
• Billing Address (street, city, state, postal code, country) → Customer Address

Light only pulls the account record itself. Contacts associated with the account don't sync. See What doesn't sync, below.

Products: every active, non-archived Salesforce product syncs to Light by default.

• Product Name → Light Product Name
• Standard Price Book Entries → Light Product Pricing (currency and unit price)

# Quotes

Quotes and Quote Line Items sync as part of the Opportunity, not as a separate sync source. Light reads a Quote only through the Opportunity it's attached to, using the Opportunity's own field mapping.

This has two practical effects:

• The Opportunity must be Closed Won before its Quote data syncs. A Quote on an open Opportunity doesn't create or update anything in Light.
• Updating a Quote by itself doesn't trigger a sync and doesn't change the Light record. Light picks up Quote data when the Opportunity it belongs to syncs, not when the Quote changes.

An Opportunity with no Quote attached syncs normally. Quotes are optional, not a requirement for the sync to run.

# What doesn't sync

# Duplicate handling

Light matches records using the Salesforce record ID, stored on the Light record as its external ID.

• If a Light customer, contract, or product already exists with that Salesforce ID, the sync updates it instead of creating a duplicate.
• If no match exists, Light creates a new record and stores the Salesforce ID as its external ID.

This applies automatically to every sync.

# Sync frequency and manual sync

Once you publish the Salesforce to Light workflow, Light polls Salesforce for new and changed records on a recurring schedule that Light manages for you.

To sync sooner, for example right after closing a large deal:

1. Go to Settings → Integrations → Salesforce.
2. Select Initiate a sync.
3. Light pulls the matching Salesforce records and runs them through the Salesforce to Light workflow immediately.

# Monitoring and troubleshooting sync

Every synced record shows up as a workflow run, so you can see exactly what happened.

1. Go to Settings → Workflows and open Salesforce to Light.
2. Each run shows which records were processed, which synced successfully, and which failed, with a reason.

Common causes of a failed sync:

• The Salesforce account on the opportunity doesn't match a Light customer by external ID.
• The sync filter matches more than one Salesforce record for the same external ID.
• The opportunity is missing an account.

To resolve a failure: fix the underlying data in Salesforce, then retry the sync from the workflow run.

Other issues:

• Opportunities not syncing: check the filter criteria, confirm the opportunity is Closed Won (or matches your custom filter), and confirm the amount field is populated.
• Wrong customer assigned: check the account mapping and look for duplicate customer names in Light.
• Duplicate invoices: confirm the filter isn't re-matching opportunities that already synced.
• Connection failed: re-authorize the Salesforce connection, and confirm your Salesforce user has API access enabled.

# Custom field mapping

Map any Salesforce field, standard or custom, to a Light property, as long as the field sits on Account, Opportunity, Quote or Product. Custom objects, and fields that live on them, are outside the integration's reach. See What doesn't sync, above.

1. Create the custom field in Salesforce, for example Project Code or Product Category.

2. In the workflow's mapping node, add the mapping, for example:

   • Project Code → Light Project Cost Center
   • Product Category → Light Invoice Line Item Product

3. Light syncs the field to the mapped Light property on every future sync.

Use these custom properties for reporting and cost allocation.

# Reporting and exporting synced data

Once opportunities are syncing into Light as invoices, use that data for revenue reporting:

• Revenue by customer
• Revenue by product
• Revenue by sales rep (from the Salesforce owner field)
• Salesforce pipeline compared against recognized revenue in Light

To export the underlying records:

1. Go to Planning & Reports → Reports.
2. Filter by date, customer, or amount.
3. Export to Excel or PDF.

# Unsyncing or reversing a record

If a record synced with the wrong data:

1. Open the Light invoice created from the Salesforce record.
2. Select Delete if it's still a draft, or Create Reversal if it's already posted.
3. Correct the data in Salesforce, then trigger the sync again.

Light keeps an audit trail of every deleted or reversed record.

# Related articles

• Integrations Overview
• HubSpot Integration
• API Access and Custom Integrations
• Profit and Loss

Also searched as: Connect Salesforce to Light, Salesforce CRM integration, sync Salesforce opportunities, Salesforce to Light workflow, Salesforce opportunity to invoice, Salesforce field mapping, Salesforce sync failed, Salesforce duplicate customer, Salesforce quote sync, does Salesforce sync contacts, Light CRM integration