--- title: "How to Create ERP-Specific Mapping Guides for NetSuite, SAP, and Dynamics 365" slug: how-to-create-erp-specific-mapping-guides-for-netsuite-and-other-erps date: 2026-05-26 author: Yuvraj Muley categories: [Guides, By Example, Engineering] excerpt: "Learn how to architect declarative ERP mapping guides for NetSuite, SAP, and Dynamics 365 using JSONata, polymorphic routing, and a 3-level override hierarchy." tldr: "Stop hardcoding ERP integrations. Use declarative JSONata mappings, SuiteQL-first reads, polymorphic routing, and a 3-level override hierarchy to map complex NetSuite and SAP data models without custom code." canonical: https://truto.one/blog/how-to-create-erp-specific-mapping-guides-for-netsuite-and-other-erps/ --- # How to Create ERP-Specific Mapping Guides for NetSuite, SAP, and Dynamics 365 If you sell B2B SaaS to mid-market or enterprise buyers, your NetSuite, SAP, or Microsoft Dynamics integration is the most expensive line item on your engineering roadmap that nobody talks about until it breaks. A massive enterprise deal closes, contingent on a NetSuite integration. The engineering team looks at the vendor API documentation, estimates two sprints for the build, and proceeds to spend the next three months debugging opaque error codes, undocumented schema behaviors, and token refresh failures. The fix is not another sprint of custom TypeScript per customer. It is a documented, declarative mapping strategy that treats each ERP integration as a configurable data contract instead of a hand-coded connector. This guide breaks down exactly how senior product managers and integration architects design, structure, and execute declarative mapping strategies for complex ERPs. We will cover the architectural patterns required to handle NetSuite's fragmented API surfaces, how to manage per-customer schema drift without writing custom code, and why abstracting the connection layer is the only way to scale enterprise integrations. ## The ERP Integration Cliff: Why Standard Mapping Fails **Short answer:** ERPs are not standard SaaS APIs. They are highly customized accounting systems with API skins on top, configured differently in every single tenant. A mapping strategy that works for a CRM like HubSpot will silently corrupt journal entries in NetSuite. Industry studies consistently show that ERP integration projects fail not because APIs physically break, but because data mapping errors cause duplicate records, rejected transactions, and silent data corruption weeks after deployment. The data behind building SaaS integrations is unforgiving. 90% of B2B buyers agree or strongly agree that a vendor's ability to integrate with their existing technology significantly influences their decision to add them to the shortlist. Worse, 51% of decision-makers cite poor integration with their existing tech stack as a primary reason to explore new vendors. 77% of buyers prioritize integration capabilities, and solutions that fail to integrate seamlessly with existing workflows are often deprioritized regardless of features or price. ERPs sit at the center of that integration story for finance, procurement, and HR-adjacent SaaS. The trap is treating an ERP like a CRM. Salesforce custom fields are annoying, but NetSuite custom segments, custom transaction types, multi-subsidiary architectures, multi-book accounting, and tax nexus rules are an entirely different category of complexity. When a B2B SaaS company attempts to build an ERP integration, they usually start by reading the standard object documentation. They map their internal `Company` object to the ERP's `Customer` object. They deploy the code. Then the first enterprise customer connects their account, and the integration immediately fails. The failure occurs because enterprise ERPs are heavily customized. A mid-market manufacturing company using NetSuite does not use the standard `Customer` object. They have added forty custom fields, renamed standard fields, and implemented custom validation scripts that reject API payloads missing specific, undocumented parameters. A standard mapping that assumes a single currency, a single subsidiary, and the stock chart of accounts will pass your test suite and then fail the first time a customer turns on NetSuite OneWorld. The symptoms are predictable: duplicate vendor records, foreign-currency invoices booked at the wrong exchange rate, transactions rejected at posting because a required segment is missing, and the dreaded silent write that succeeds at the API layer but never appears in a saved search. To survive the ERP integration cliff, your architecture must adapt to the specific shape of the customer's data model at runtime. If your integration relies on a direct, hardcoded connection to a legacy system, [an upstream migration will break your application](https://truto.one/migrating-legacy-on-premise-erps-to-cloud-apis-without-downtime/). ## Why NetSuite API Mapping Is Uniquely Difficult NetSuite represents the final boss of API integrations. Unlike simpler REST APIs that expose a single, uniform surface, NetSuite exposes data through four distinct API surfaces, and any serious production integration uses at least three of them to achieve feature parity. ### The Four Faces of the NetSuite API 1. **SuiteTalk REST:** The modern, JSON-based API. It handles most basic CRUD operations on standard records. However, it is notoriously bad at complex JOINs and filtering. If you need to pull a list of invoices filtered by a specific line-item property, SuiteTalk REST will force you to paginate through thousands of records and filter them in memory. 2. **SuiteTalk SOAP:** The legacy XML API. While modern architectures avoid SOAP, NetSuite still hides certain critical data behind it. For example, retrieving detailed sales tax item configurations often requires falling back to the legacy SOAP `getList` operation because the modern REST endpoints simply do not expose the full tax rate schema. 3. **RESTlets (SuiteScript):** NetSuite's serverless compute layer. You can deploy custom JavaScript (SuiteScript) directly into the customer's NetSuite instance and expose it as a REST endpoint. This is absolutely required for capabilities that the standard APIs cannot provide, such as generating Purchase Order PDFs or extracting dynamic form field metadata (including select options and mandatory flags). 4. **SuiteQL:** NetSuite's SQL-like query language. This is the most powerful read layer available. It runs over the underlying record database, allowing multi-table JOINs, complex filtering, aggregations, and significantly better performance than the REST record API. > [!WARNING] > **Authentication Deprecation Notice:** NetSuite relies heavily on OAuth 1.0 Token-Based Authentication (TBA), which requires generating complex HMAC-SHA256 signatures for every request. As of the NetSuite 2027.1 release, you will no longer be able to create new integrations using the TBA feature with SOAP web services, REST web services, and RESTlets. Existing integrations using TBA will continue to work, but all newly created integrations must use the OAuth 2.0 authorization code grant flow and must include PKCE parameters. If your mapping guide does not specify which auth flow each connector uses and whether it supports PKCE, you are writing technical debt. To map data effectively, your integration architecture must intelligently route requests to the correct surface based on the operation. A unified `invoices.list` operation cannot just be a single SuiteQL query. It needs to know when to enrich results with REST lookups, when to fall back to SOAP for tax detail, and how to detect at connection time whether the tenant has multi-currency enabled so the JOINs are conditional. ```mermaid flowchart LR A[Unified API Request] --> B{Operation Type} B -->|Complex Read / List| C[SuiteQL Query Builder] B -->|Standard Write| D[SuiteTalk REST] B -->|Custom Logic / PDF Gen| E[Deployed RESTlet SuiteScript] B -->|Legacy Schema / Tax Rates| F[SuiteTalk SOAP] C --> G[Feature Detection:
OneWorld / Multi-Currency] G --> H[Conditional JOINs] H --> I[Normalized Unified Response] D --> I E --> I F --> I ``` ## The Problem with Hardcoded Mappings and Rigid Unified APIs Faced with this complexity, engineering teams typically fall into one of two architectural traps, and most teams alternate between them. **Trap 1: Writing Custom TypeScript for Every Customer** The brute-force approach. Engineering writes TypeScript or Python that knows how to map Acme Corp's NetSuite chart of accounts to your product's internal schema. When a customer needs a custom field mapped, an engineer writes a custom `if (customer === 'Acme')` block in the integration handler. When a second customer signs up with a different chart of accounts and three custom segments, you fork the file. As the customer base grows, you end up with a `customer-mappers/` directory that nobody wants to touch, zero test coverage, and a tribal-knowledge dependency on one engineer. Adding a new field requires a pull request, code review, CI/CD pipeline execution, and a production deployment. This destroys engineering velocity and makes the integration impossible to maintain. **Trap 2: Using Rigid Unified APIs with Fixed Schemas** To avoid writing custom code, teams adopt legacy unified API platforms. These platforms normalize data into rigid, lowest-common-denominator schemas. You buy or build a unified accounting layer with a `LineItem` object that has 12 standard fields. They map the standard `name` and `email` fields but strip away the deep, ERP-specific customizations that the enterprise customer actually cares about. When the first enterprise customer has 14 custom segments per line item that drive their internal cost allocation, the rigid unified API either drops those fields, shoves them into an unstructured `metadata` blob, or forces you to make a separate "raw" passthrough call to get them. This completely defeats the point of unification. Both failure modes share a root cause: the mapping is encoded in imperative code or in a fixed schema, when it should be encoded as data that can be versioned, overridden, and inspected. ## Architecting a Declarative ERP Data Mapping Strategy The architectural solution is to separate the *mechanism* of the integration from the *mapping* of the data. You achieve this by treating API mappings as declarative data operations rather than code deployments. Field translations become expressions instead of imperative code. The runtime engine reads the expression and applies it to the upstream payload. The transformation language matters. At Truto, we use **JSONata** as the universal transformation language because it satisfies four critical constraints that other options (like custom DSLs) fail at least one of: 1. **Self-contained:** A single string expression can represent a full field mapping, including conditionals and date arithmetic. 2. **Side-effect free:** Transformations are pure functions, which means they are testable in isolation and safe to run in parallel. 3. **Turing-complete enough:** It supports recursion, string manipulation, and custom function libraries for edge cases. 4. **Storable as data:** The expression lives in a database row, not a code file, so it can be versioned and hot-swapped without a deploy. When you use JSONata, adding a new mapping or handling a custom field is a data operation, not a code deployment. [You can ship new API connectors as data-only operations](https://truto.one/zero-integration-specific-code-how-to-ship-new-api-connectors-as-data-only-operations/). ### Example 1: Basic Declarative NetSuite Entity Mapping Instead of writing TypeScript to parse a NetSuite response, you store a JSONata expression that defines exactly how the native ERP payload translates into your unified schema. This handles conditional logic, type coercion, and nested object extraction. ```json { "id": internalId, "name": companyName, "email": email, "currency": currency.name, "custom_fields": { "region_code": custentity_region_code, "tax_exempt": custentity_is_exempt = 'T' ? true : false } } ``` ### Example 2: Complex Transaction Mapping A mapping for a NetSuite vendor bill to a unified `bill` resource ends up looking like configuration, not code. Notice how line items are mapped and custom segments are dynamically extracted. ```json { "unified_resource": "bills", "native_resource": "vendorbill", "response_mapping": { "id": "id", "vendor_id": "entity.id", "currency": "currency.refName", "total": "$number(total)", "subsidiary_id": "subsidiary.id ? subsidiary.id : null", "line_items": "item.items.{ \"id\": id, \"amount\": $number(amount), \"account_id\": account.id, \"custom_segments\": $.{ }[$startsWith(key, 'cseg_')] }" }, "query_mapping": { "updated_after": "'lastModifiedDate >= ' & $iso2netsuiteDate(updated_after)" } } ``` Notice what is not in the file: there is no `if (integration === 'netsuite')` branch anywhere in the runtime. The same generic execution engine that runs this config also runs the SAP, QuickBooks, and Microsoft Dynamics configs. Adding a new ERP is an exercise in writing a config, not modifying the engine. > [!TIP] > A good test for whether your mapping is declarative enough: can a senior product manager with SQL fluency read and modify it without a deploy? If the answer is no, the mapping is still code in disguise. ## Handling Custom Fields and Polymorphic Routing in ERPs The two patterns that break naive unified APIs are custom fields and polymorphic resources. Both are ubiquitous in NetSuite and SAP. A mapping guide must account for structural mismatches between your product's data model and the ERP's architecture. ### Custom Field Prefix Extraction Custom fields in NetSuite come in several flavors: `custbody_` for transaction body fields, `custcol_` for transaction line fields, `custentity_` for entity records, and `cseg_` for custom segments that participate in classifications. Your mapping guide needs to specify exactly how each prefix is detected and surfaced. The pragmatic approach is to pass through any field matching these prefixes into a `custom_fields` object on the unified response, with the original NetSuite internal ID preserved as the key. Writes work in reverse: anything in the consumer's `custom_fields` payload gets serialized back with the correct prefix. This only works if your unified schema allows custom fields to coexist with normalized fields. The same constraint applies to [handling custom Salesforce objects via API](https://truto.one/how-to-handle-custom-fields-and-custom-objects-in-salesforce-via-api/). ### Polymorphic Resource Routing In your SaaS application, you might have a single concept of a `Contact`. In NetSuite, that entity might be stored as a `Customer`, a `Vendor`, or an `Employee` depending on their relationship to the business. Hardcoding separate integrations for each entity type pushes the complexity onto the consumer. Instead, implement **polymorphic resource routing**. A single unified `contacts` resource dynamically routes to the correct NetSuite endpoint based on context. Let the declarative mapping layer dispatch the call: ```json { "unified_resource": "contacts", "resource_router": { "expression": "type = 'vendor' ? 'vendor' : 'customer'", "targets": { "vendor": { "native_resource": "vendor", "mapping": "..." }, "customer": { "native_resource": "customer", "mapping": "..." } } } } ``` If the API consumer passes a query parameter `?type=vendor`, the declarative routing engine intercepts the request, dynamically rewrites the destination URL to the NetSuite `vendor` endpoint, and applies the vendor-specific JSONata mapping. The consumer experiences a clean, unified REST interface. The exact same pattern works for SAP material vs. service items, or Dynamics 365 account vs. contact distinctions. ### SuiteQL-First Data Strategy and Feature-Adaptive Queries To extract data reliably, you must default to SuiteQL for read operations. This unlocks the multi-table JOINs you cannot express through the record API. Instead of fetching a list of bills and then making N follow-up calls for vendor details, currency, and subsidiary, you write one SuiteQL query that joins them. However, SuiteQL queries cannot be static. NetSuite instances come in different editions. A customer on NetSuite OneWorld uses a multi-subsidiary architecture, meaning their database contains `subsidiary` tables that must be joined to retrieve accurate financial records. A customer on a standard NetSuite edition does not have these tables. If you hardcode a SuiteQL query with a `JOIN subsidiary`, the query will hard-crash on standard editions. Your mapping architecture must utilize **feature-adaptive queries**. At connection time, the integration must automatically detect the customer's NetSuite edition and feature flags. The mapping layer then dynamically includes or excludes specific JOINs and columns based on that context. ```sql -- The mapping layer dynamically injects the subsidiary JOIN only if the feature flag is detected SELECT Transaction.ID, Transaction.TranID, Transaction.Type {{#if hasOneWorld}} , Subsidiary.Name AS SubsidiaryName {{/if}} FROM Transaction {{#if hasOneWorld}} LEFT JOIN Subsidiary ON Transaction.Subsidiary = Subsidiary.ID {{/if}} WHERE Transaction.Type = 'CustInvc' ``` The mapping guide should document this conditional-query behavior explicitly so consumers understand why the same unified call returns different shapes on different tenants. ## The 3-Level Override Hierarchy for Per-Customer Customization The true test of an ERP integration is how it handles the inevitable customer who needs a completely bespoke data model. One customer needs their `internal_po_number` custom field surfaced as a top-level unified attribute. Another needs a pre-request step to look up a default location ID. A third wants a specific custom segment included in every line item response. If your architecture requires engineering intervention to support a custom NetSuite workflow, you will drain your R&D budget on implementation services. The answer is not to fork the mapping per customer. To scale without code, you must implement a [multi-level override hierarchy](https://truto.one/per-customer-api-mappings-3-level-overrides-for-enterprise-saas/). The system evaluates mappings at three distinct levels, deep-merging the configuration at runtime using a [3-level JSONata architecture](https://truto.one/per-customer-data-model-customization-without-code-the-3-level-jsonata-architecture/). | Level | Scope | Use Case | | :--- | :--- | :--- | | **Level 1: Platform Base** | Default mapping for the integration. | Works for 80% of customers. Maps standard fields like `name`, `email`, and `balance` to your unified schema. | | **Level 2: Environment Override** | Per-environment override applied to a segment. | Your staging vs. production OAuth apps, or applying a JSONata date-formatting override for a specific cohort of tenants. | | **Level 3: Account Override** | Per-connected-account override. | One enterprise customer's highly specific custom field (`custbody_approval_status`) that needs to be mapped to the unified `status` field. | ### What Can Be Overridden Declaratively? * **`response_mapping`**: JSONata expression reshaping the ERP response (e.g., extracting nested custom fields into flat unified properties). * **`query_mapping`**: JSONata expression translating unified query parameters (e.g., translating `?updated_after=date` into a complex SuiteQL `WHERE` clause). * **`request_body_mapping`**: JSONata expression formatting outbound payloads (e.g., injecting mandatory custom fields required by a tenant's validation scripts). * **`resource`**: The native API endpoint path (e.g., routing a standard write operation to a custom deployed RESTlet instead of the standard REST API). A concrete example: your platform mapping for NetSuite invoices includes 15 standard fields. Enterprise Customer A has a custom segment `cseg_region` they want exposed as `region`. An implementation engineer adds an account-level override directly to their connection record: ```json { "response_mapping": { "region": "cseg_region.refName" } } ``` When the unified call runs for Customer A's account, this override merges on top of the platform mapping. Every other customer's response remains unchanged. There is no fork of the integration, no special code path, and no deploy. The [3-level API mapping pattern](https://truto.one/3-level-api-mapping-per-customer-data-model-overrides-without-code/) is what makes ERP integrations scale past 10 enterprise customers without engineering becoming a per-tenant bottleneck. > [!WARNING] > Override hierarchies are a footgun without governance. Document who can edit each level, require change reviews for environment-level changes, and log every override application so you can debug "why is this field showing up" questions six months later. ## Standardizing Rate Limits and Error Handling ERP APIs are incredibly aggressive about rate limiting. NetSuite governs by concurrency limits based on the customer's license tier. SAP S/4HANA Cloud has strict per-tenant call quotas. Dynamics enforces API entitlements. If you blast the API with parallel requests, it will quickly return HTTP 429 (Too Many Requests) errors. A critical architectural decision is how to handle these limits. Your mapping guide needs to commit to a consistent error and rate-limit contract across all providers, or your consumers will write provider-specific handling for every connector. Many teams attempt to build complex, stateful queueing systems to absorb and silently retry rate limit errors on behalf of the caller. This is an anti-pattern. Hidden retries inside an integration layer create cascading load on the upstream ERP precisely when it is rate limiting you, lead to the thundering herd problem, and hide failures from the consumer's observability. **Factual architectural guidance:** Do not retry, throttle, or apply exponential backoff on rate limit errors inside the integration platform. When an upstream ERP API returns an HTTP 429, pass that error directly back to the caller. However, every ERP formats its rate limit headers differently. Some use `X-RateLimit-Remaining`, others use `Retry-After`, and some bury the limit inside the JSON response body. To make this actionable for the caller, the mapping layer must normalize the upstream rate limit information into standardized IETF headers: * `ratelimit-limit`: The total request quota available. * `ratelimit-remaining`: The number of requests left in the current window. * `ratelimit-reset`: The timestamp when the quota refreshes. By normalizing the headers but passing the 429 error through, the integration platform provides the exact telemetry the caller needs to implement intelligent, context-aware retry and backoff logic in their own application layer. Retry policy is a product decision that belongs to the consumer, who knows whether the operation is idempotent and whether the user is waiting on a response. For the deeper rationale, see [Best Practices for Handling API Rate Limits](https://truto.one/best-practices-for-handling-api-rate-limits-and-retries-across-multiple-third-party-apis/). For 5xx errors and connectivity failures, your mapping guide should document which operations are idempotent (most reads, PUT-style upserts with deterministic IDs) and which are not (creates without external IDs). Consumers can then apply idempotency keys and bounded exponential backoff where it is safe. ## What an ERP Mapping Guide Should Actually Contain If you are publishing internal or customer-facing ERP mapping documentation, the artifacts that matter are highly technical and specific. Enterprise procurement teams read this to ensure you [aren't caching sensitive financial data](https://truto.one/how-to-build-erp-integrations-netsuite-sap-without-storing-data/). So do the security architects who veto your deal, and the integration partners who decide whether to certify you. A serious ERP integration without serious mapping documentation is a tell that you have not built one. Your guide must contain: * **API surface map**: Which unified operations route to REST vs. SOAP vs. RESTlet vs. SuiteQL, and why. * **Feature-detection matrix**: Which tenant features (OneWorld, multi-currency, multi-book, advanced taxes) change query construction, and how the platform detects them. * **Field mapping reference**: Every unified field, its source expression, its handling of nulls, and any JSONata transformation applied. * **Custom field policy**: How `custbody_`, `custcol_`, `custentity_`, and `cseg_` fields are detected and surfaced on both reads and writes. * **Polymorphic routing rules**: How a unified resource resolves to a native resource based on query parameters or payload. * **Override examples**: At least one realistic environment-level override and one account-level override with the merged result. * **Auth and migration notes**: Which auth schemes are supported, the PKCE requirement timeline, and the migration path off TBA before 2027.1. * **Rate limit and error contract**: How upstream limits are surfaced, which errors are retried at which layer, and which operations are idempotent. ## Stop Writing Code for ERP Integrations Building an integration to NetSuite, SAP, or Dynamics is an exercise in managing chaos. The API surfaces are fragmented, the documentation is unreliable, and every customer instance features a bespoke schema that will break hardcoded integration logic. The shift from code-per-customer to declarative-mapping-per-resource is the single highest-leverage change you can make to your ERP integration strategy. It does not eliminate complexity. It moves the complexity into a structure that product managers can reason about, that solutions engineers can customize per customer without filing engineering tickets, and that survives the inevitable NetSuite release that breaks your assumptions. The next steps if you are starting from a code-heavy ERP integration today: 1. **Audit your current mappings:** Count how many `if (customer === X)` branches exist in your integration code. That number is your tech debt. 2. **Choose a transformation language:** Pick a language that is declarative, storable, and side-effect free, like JSONata. 3. **Define your override layers:** Establish platform, environment, and account override layers before you need them. Retrofitting a hierarchy onto a flat mapping system is painful. 4. **Plan the TBA-to-OAuth-2.0 migration:** For NetSuite, the 2027.1 deadline is closer than your roadmap suggests. 5. **Publish your mapping guide:** Enterprise buyers will read it, and it will close deals. When you abstract the connection layer and treat API mapping as configuration, you transform chaotic ERP builds into a predictable, scalable product line. > Stop hardcoding ERP integrations. See how Truto's declarative mapping engine and 3-level override hierarchy handles deep ERP customization without the per-customer code tax. Book a 30-minute architecture review with our team. > > [Talk to us](https://cal.com/truto/partner-with-truto)