.svg){kind=small}
At a glance
What it does: Creates a NetSuite invoice from a closed-won Salesforce Opportunity, mapping header fields and OpportunityLineItems to invoice lines, then writes the NetSuite invoice ID back to Salesforce.
When to trigger: Opportunity stage changes to Closed Won (with validation that required fields are populated and line items exist).
Inputs: Salesforce Opportunity (Account, Close Date, Amount, Currency, custom fields for terms/PO) and OpportunityLineItems (Product, Quantity, Unit Price, Total Price).
Outputs: A posted NetSuite invoice with line items, plus a NetSuite invoice ID and document number stored on the Salesforce Opportunity.
Key assumptions: Each Opportunity produces one invoice. Customers and items already exist in NetSuite (or you have defined create-on-the-fly rules). Tax is calculated in NetSuite unless otherwise configured.
Out of scope: Payment application, revenue recognition, subscription billing, credit memos.
Related: How to Sync Salesforce & HubSpot Deals to NetSuite and Sage Intacct Invoices · NetSuite + Stripe + Salesforce Integration Guide · How LedgerUp Automates Salesforce & HubSpot Deals to Invoices
Field mapping quick reference
This shortened table covers the most frequently mapped fields. Full mapping tables with edge-case notes appear later in the guide.
Data model decisions to make first
Before touching configuration, lock down five decisions that affect every downstream mapping. Skipping these leads to rework once edge cases surface in production.
Customer mapping (Account to NetSuite Customer)
Every NetSuite invoice requires a customer (the entity field). The most reliable approach is storing the NetSuite Customer internal ID or external ID as a custom field on the Salesforce Account, then looking up by that key. Name matching is fragile ("Inc." vs "Inc" vs trailing spaces).
Decide whether the integration should auto-create a NetSuite Customer when no match is found, or fail and alert. Auto-creation is convenient but produces duplicates if matching logic is loose.
Item mapping (Products to NetSuite Items)
Each OpportunityLineItem references a Salesforce Product. That Product must map to a NetSuite Item. Maintain a cross-reference, either as a custom field on the Salesforce Product record or in a mapping table within the integration layer.
Decide what happens when a Product has no matching NetSuite Item: fail the entire invoice, substitute a generic item, or create the item on the fly.
OneWorld subsidiary and currency
If your NetSuite account uses OneWorld, every invoice is tied to one subsidiary. The Oracle OneWorld documentation states that when a transaction includes an entity like a customer, the transaction is assigned to the same subsidiary as that entity. The integration must confirm the customer's subsidiary matches the intended billing subsidiary.
For multi-currency, confirm the Opportunity currency is enabled on both the NetSuite Customer record and the subsidiary.
Taxes
Define where tax is calculated. Common options: NetSuite calculates tax natively (SuiteTax or Legacy Tax), a third-party engine like Avalara handles it, or tax amounts come from Salesforce. If NetSuite handles tax, the integration needs to pass the correct tax code per line or let NetSuite default it from item and customer settings.
Terms, due dates, and PO numbers
Identify the source of truth for payment terms. If terms live on the Opportunity (custom field), map them to the NetSuite terms field. If terms are set on the NetSuite Customer record, the invoice can inherit them.
Step-by-step: set up Salesforce to NetSuite invoice sync
Step 1: Choose the trigger condition
Use a stage transition to "Closed Won" as the primary trigger. Combine the stage check with field validation: Account must be populated, at least one OpportunityLineItem must exist, and Amount must be greater than zero. Avoid triggering on every Opportunity save event; a specific stage transition or a finance-controlled checkbox keeps the sync predictable.
Step 2: Define the invoice creation rule
For a standard sync, one Opportunity equals one invoice. If you need milestone billing or split invoices, define those rules now, including which OpportunityLineItems go on which invoice and how partial amounts are tracked.
Step 3: Map the customer (Account to NetSuite Customer)
Before creating the invoice, resolve the NetSuite Customer using a matching key (external ID, stored internal ID, or a shared identifier on the Salesforce Account). If no match is found, either auto-create the Customer or fail with an alert. Confirm the customer's subsidiary and currency are compatible with the invoice.
Step 4: Map invoice header fields
Map the header from Opportunity and Account data:
- Date: Close Date or today's date, depending on billing policy.
- Memo: Opportunity Name or a formatted reference string.
- Terms: From a custom Opportunity field, or inherited from the NetSuite Customer record.
- Currency: Opportunity currency (ISO code mapped to a NetSuite currency record).
- Subsidiary: Driven by the customer's subsidiary in OneWorld accounts.
- External ID: Salesforce Opportunity ID for idempotent creates.
Step 5: Map OpportunityLineItems to invoice lines
For each OpportunityLineItem, create a line on the NetSuite invoice's item sublist. Map Product to a NetSuite Item, then pass Quantity, Unit Price (as rate), and optionally Total Price (as amount). If classification fields like department, class, or location are required on invoice lines, define where those values originate.
Step 6: Validate tax and totals
Before posting, compare the expected total (sum of Salesforce line amounts plus any tax) against the NetSuite-calculated total. If NetSuite handles tax, the invoice total will exceed the Salesforce Opportunity Amount by the tax amount, and that difference is expected. Define a tolerance threshold (for example, $0.01 for rounding) and alert on anything outside it.
Step 7: Write back NetSuite invoice ID to Salesforce
After the invoice posts, store the NetSuite invoice internal ID and document number on the Salesforce Opportunity using a custom field (for example, "NetSuite Invoice ID"). The write-back gives sales and finance a direct reference.
Step 8: Handle errors and retries
Not every sync will succeed on the first attempt. Design for three categories of failure:
- Transient errors (timeouts, rate limits): Retry automatically with exponential backoff up to a defined limit (for example, three retries over 15 minutes).
- Data errors (missing customer, missing item, invalid tax code): Fail fast, log the specific field and value that caused the failure, and alert the team. These require a human fix before retrying.
- Partial failures (3 of 5 line items map but 2 don't): Decide up front whether to create a partial invoice or reject the entire sync. Most finance teams prefer all-or-nothing to avoid reconciliation headaches.
Queue-based processing helps here. Push each closed-won Opportunity into a processing queue, and let a worker handle retries and dead-letter routing for unresolvable failures.
Step 9: Test, monitor, and roll out
Run end-to-end tests in sandbox for both systems. Include edge cases: multi-currency deals, missing customers, missing items, zero-quantity lines, and duplicate triggers. Set up error alerting so failed syncs surface immediately.
Prerequisites
Salesforce prerequisites
Opportunities must have OpportunityLineItems consistently populated. If reps close deals without adding Products, the integration has nothing to map to invoice lines. Run a report on recent closed-won Opportunities and check for zero line items, blank Accounts, or missing amounts.
Confirm that Account, Close Date, and Amount are reliably filled. If custom fields exist for payment terms, PO number, or billing entity, verify those fields are required or defaulted at the Opportunity level.
NetSuite prerequisites
Confirm the invoice transaction form supports API-created records (some custom forms restrict entry channels). Verify that Items your Salesforce Products map to exist, are active, and are available in the correct subsidiary if you use OneWorld.
Check A/R account configuration, tax setup, and any mandatory classification fields (department, class, location). Which fields are mandatory depends on enabled features and account preferences.
Permissions and authentication
Salesforce: The integration user needs read access to Opportunity, OpportunityLineItem, Account, Product2, and PricebookEntry objects. If writing back NetSuite identifiers, the user also needs update access on Opportunity or a custom object.
NetSuite: The integration role needs permissions to create invoices, read customers, and read items. Use token-based authentication (TBA) or OAuth 2.0 with a dedicated role scoped to minimum required permissions.
Full field mapping table (Salesforce to NetSuite)
Field names on the Salesforce side vary by org. The labels below represent common configurations. Confirm exact Salesforce API names before implementation.
Invoice header mapping
Invoice line mapping (OpportunityLineItems)
Recommended external ID strategy
Set externalId on every NetSuite invoice you create. Use the Salesforce Opportunity ID (18-character, stable) as the value. If a single Opportunity can produce multiple invoices, append a sequence number (for example, 0068A00000XyZ1234_1).
External IDs in NetSuite are not case-sensitive. Attempting to create an invoice with a duplicate external ID returns a 400 error with a "This entity already exists" message. Treat that error as confirmation the invoice was already created (idempotency), not as a failure to retry.
Common issues and troubleshooting
- Customer not found or duplicate customers: Verify matching key resolves to one active customer. Check for trailing whitespace, abbreviation differences ("Inc." vs "Inc"), and inactive customer records.
- Item not found or inactive: Confirm Product-to-Item mapping and item subsidiary availability. Verify the item is not restricted to a different subsidiary or marked inactive.
- OneWorld subsidiary mismatch: Customer subsidiary drives invoice subsidiary in OneWorld. You cannot override this at the transaction level.
- Tax code required: Validate tax codes per item and customer configuration. If SuiteTax is enabled, ensure nexus assignments are complete.
- Amount mismatch: Check rounding, discounts, tax-inclusive vs tax-exclusive pricing, and whether the integration passes
rate × quantityoramountdirectly. - Duplicate invoice creation: Enforce external ID and treat 400 duplicate as idempotency, not a retry-able error.
- Missing OpportunityLineItems: Block sync when line items are missing or zero quantity. Run a Salesforce report to identify Opportunities missing line items before go-live.
FAQ
Can one Opportunity create multiple NetSuite invoices?
Yes, but the external ID strategy must include a sequence suffix per invoice (for example, appending _1, _2 to the Opportunity ID). You also need to define the business rules for which OpportunityLineItems go on which invoice, whether that is milestone-based, by product type, or by billing schedule. Track the relationship between the parent Opportunity and each generated invoice to maintain auditability.
What happens if an Opportunity has no OpportunityLineItems?
The sync should fail fast and alert the team. Without line items, the integration has no products, quantities, or rates to map to invoice lines, which means the resulting NetSuite invoice would either be empty (and rejected by NetSuite) or require manual entry that defeats the purpose of automation. Build a pre-sync validation that checks for at least one OpportunityLineItem with a quantity greater than zero before triggering invoice creation.
Does OneWorld let the integration pick any subsidiary?
No. In OneWorld, invoices inherit the subsidiary from the customer entity. The integration cannot set the subsidiary independently of the customer. If the Opportunity references a different subsidiary than the customer's, the sync should catch this mismatch during validation and surface an error before attempting invoice creation. (Source: Oracle OneWorld documentation)
Should tax be calculated in Salesforce or NetSuite?
Most teams calculate tax in NetSuite and pass tax codes or defaults from item and customer settings. This approach keeps the tax engine centralized in the ERP, avoids discrepancies between CRM and ERP tax calculations, and simplifies compliance when tax rules change. If you use a third-party engine like Avalara, it typically integrates with NetSuite to calculate tax at invoice creation time.
How are duplicates prevented during retries?
Set externalId on every invoice using the Salesforce Opportunity ID as the value. When a retry attempts to create an invoice with the same external ID, NetSuite returns a 400 error indicating the entity already exists. Your integration should catch this specific error and treat it as confirmation that the invoice was already created successfully, rather than a failure requiring further retries. This pattern is called idempotent creation. (Source: Tim Dietrich on NetSuite external IDs)
What is the difference between passing rate vs amount on invoice lines?
When you pass rate (unit price) and quantity, NetSuite calculates the line amount as rate × quantity. When you pass amount directly, you are overriding NetSuite's calculation with a fixed total for that line. Most integrations pass rate and quantity so that NetSuite remains the system of record for line-level math. Pass amount only when the Salesforce line total includes adjustments (like negotiated discounts) that cannot be expressed as a simple rate × quantity calculation.
How teams automate this workflow
Manually building and maintaining a Salesforce-to-NetSuite invoice sync involves mapping fields, handling edge cases, managing retries, and monitoring for failures across two complex systems. Teams that automate this workflow typically need to:
- Create NetSuite invoices from closed-won Salesforce Opportunities without manual re-entry.
- Map Opportunity header fields and OpportunityLineItems to NetSuite invoice fields and lines.
- Resolve customer and item references using configured matching keys.
- Assign subsidiary and currency based on customer and Opportunity data.
- Set a stable external ID to prevent duplicate invoice creation on retries.
- Write back NetSuite invoice identifiers to Salesforce so sales and finance share a single source of truth.
- Surface sync failures with enough error context for fast resolution.
LedgerUp automates this entire contract-to-cash workflow, including the Salesforce-to-NetSuite invoice sync described in this guide. Rather than building and maintaining custom integration logic, teams use LedgerUp to handle field mapping, customer and item resolution, duplicate prevention, and error alerting out of the box.
Validation checklist (before go-live)
- All in-scope Salesforce Opportunities have Account, OpportunityLineItems, and required custom fields populated.
- Every Salesforce Product maps to an active NetSuite Item available in the correct subsidiary.
- Customer matching key (external ID or stored internal ID) is populated on all in-scope Accounts.
- OneWorld subsidiary mapping is confirmed and tested for at least two subsidiaries.
- Tax codes are valid for all item-customer-subsidiary combinations in test invoices.
- External ID strategy is implemented; duplicate external ID errors are handled as idempotency signals.
- NetSuite invoice ID writes back to Salesforce Opportunity after successful creation.
- Error alerting is configured and tested (simulate a failure, confirm the alert fires).
- Retry logic handles transient errors with backoff; data errors fail fast with actionable alerts.
- Sandbox tests cover: standard deal, multi-currency deal, zero-quantity line, missing customer, missing item, duplicate trigger.
- Finance team has reviewed sample test invoices in NetSuite and confirmed GL posting is correct.
Appendix: example payload and test cases
Example mapping scenario: standard deal
A Salesforce Opportunity "Acme Corp, Annual License" closes with two OpportunityLineItems:
The resulting NetSuite invoice: entity set to the Acme Corp Customer (matched by external ID), tranDate of 2025-01-15, terms mapped to Net 30, externalId of 0068A00000XyZ1234, and two item lines with corresponding NetSuite Item IDs, quantities, and rates.
Example mapping scenario: multi-currency OneWorld deal
A Salesforce Opportunity for "EuroTech GmbH" closes in EUR against a US-headquartered company using OneWorld:
The integration must verify that the EuroTech GmbH Customer in NetSuite belongs to the "EU Operations" subsidiary, that EUR is enabled on both the customer record and the subsidiary, and that the exchange rate is set (either automatically via NetSuite's currency exchange rate table or manually). If the customer's subsidiary does not match "EU Operations," the sync should fail with a clear subsidiary mismatch error.
Test cases to run
- Standard closed-won deal: Verify invoice creates with correct header, lines, and write-back to Salesforce.
- Missing customer: Close an Opportunity where the Account has no matching NetSuite Customer. Confirm the sync fails gracefully and alerts.
- Missing item: Add a Product with no NetSuite Item mapping. Confirm the invoice does not partially create.
- Duplicate trigger: Fire the sync twice for the same Opportunity. Confirm only one invoice exists (external ID prevents the duplicate).
- Multi-currency deal: Close an Opportunity in EUR against a USD-base subsidiary. Confirm currency and exchange rate handling.
- Zero-quantity line: Include an OpportunityLineItem with zero quantity. Confirm the integration skips or rejects it per your rules.
- OneWorld subsidiary mismatch: Attempt to create an invoice where the customer is in Subsidiary A but the Opportunity references Subsidiary B. Confirm the error is caught before posting.
- Transient failure retry: Simulate a timeout on the NetSuite API call. Confirm the integration retries with backoff and eventually succeeds or alerts after max retries.
- Partial line item failure: Include one valid and one unmapped Product. Confirm the integration rejects the entire invoice (or handles per your partial-failure rule).
