Integration Methods Comparison

Integration Architecture Patterns

PATTERN 1: POINT-TO-POINT (Simple)
═══════════════════════════════════════════════════════════════════

┌─────────────┐                      ┌─────────────┐
│  External   │ ───── REST/SOAP ───→ │  NetSuite   │
│   System    │ ←─────────────────── │             │
└─────────────┘                      └─────────────┘

Best for: Single integration, low volume
Risk: Hard to scale, no centralized monitoring


PATTERN 2: MIDDLEWARE/iPaaS (Scalable)
═══════════════════════════════════════════════════════════════════

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  Shopify    │ ───→ │             │ ───→ │             │
└─────────────┘      │             │      │             │
┌─────────────┐      │  Middleware │      │  NetSuite   │
│  Salesforce │ ───→ │  (Celigo,   │ ───→ │             │
└─────────────┘      │   Boomi)    │      │             │
┌─────────────┐      │             │      │             │
│  Amazon     │ ───→ │             │ ───→ │             │
└─────────────┘      └─────────────┘      └─────────────┘

Best for: Multiple integrations, complex transforms
Benefits: Centralized logging, error handling, monitoring


PATTERN 3: EVENT-DRIVEN (Real-time)
═══════════════════════════════════════════════════════════════════

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│  External   │      │   Message   │      │  NetSuite   │
│   System    │ ───→ │    Queue    │ ───→ │  (RESTlet)  │
└─────────────┘      │  (SQS/etc)  │      └─────────────┘
                     └─────────────┘
                           │
                     ┌─────────────┐
                     │   Worker    │
                     │  (process)  │
                     └─────────────┘

Best for: High volume, async processing
Benefits: Decoupled, scalable, fault-tolerant

Integration Decision Framework

Authentication Setup

OAuth 2.0 (Recommended)

OAUTH 2.0 SETUP STEPS
═══════════════════════════════════════════════════════════════════

1. CREATE INTEGRATION RECORD
   Path: Setup → Integration → Manage Integrations → New

   Settings:
   ┌─────────────────────────────────────────────────────────────┐
   │ Name: My REST Integration                                   │
   │ State: Enabled                                              │
   │                                                             │
   │ Authentication:                                             │
   │   ☑ OAuth 2.0                                               │
   │   ☑ Token-Based Authentication (TBA)                       │
   │                                                             │
   │ OAuth 2.0:                                                  │
   │   Authorization Code Grant: ☑                              │
   │   Client Credentials Grant: ☑ (machine-to-machine)         │
   │   Callback URL: https://yourapp.com/oauth/callback         │
   └─────────────────────────────────────────────────────────────┘

2. SAVE AND COPY CREDENTIALS
   After save:
   - Consumer Key (Client ID): Copy immediately
   - Consumer Secret (Client Secret): Copy immediately (shown once)

3. GENERATE ACCESS TOKEN
   For Client Credentials (M2M):

   POST https://{account_id}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=client_credentials
   &client_id={consumer_key}
   &client_secret={consumer_secret}

   Response:
   {
     "access_token": "eyJ0...",
     "token_type": "Bearer",
     "expires_in": 3600
   }

Token-Based Authentication (TBA)

TBA SETUP (Legacy but widely used)
═══════════════════════════════════════════════════════════════════

1. Enable TBA Feature
   Path: Setup → Company → Enable Features → SuiteCloud
   ☑ Token-Based Authentication

2. Create Integration Record (same as OAuth)
   ☑ Token-Based Authentication

3. Create Access Token
   Path: Setup → Users/Roles → Access Tokens → New

   Fields:
   - Application: [Select your integration]
   - User: [Integration user with appropriate role]
   - Token Name: My API Token

4. Copy Credentials (shown once):
   - Token ID
   - Token Secret

5. Use in API Calls:
   Authorization header requires OAuth 1.0 signature
   (Most libraries handle this automatically)

REST API Examples

Get Customer

GET /services/rest/record/v1/customer/123
Authorization: Bearer {access_token}

Response:
{
  "id": "123",
  "companyName": "Acme Corp",
  "email": "info@acme.com",
  "phone": "555-1234",
  "subsidiary": {
    "id": "1",
    "refName": "US Operations"
  },
  "links": [
    {"rel": "self", "href": "/services/rest/record/v1/customer/123"}
  ]
}

Create Sales Order

POST /services/rest/record/v1/salesOrder
Authorization: Bearer {access_token}
Content-Type: application/json
Prefer: respond-async  // For large orders

{
  "entity": {"id": "123"},
  "tranDate": "2024-12-10",
  "subsidiary": {"id": "1"},
  "location": {"id": "1"},
  "item": {
    "items": [
      {
        "item": {"id": "456"},
        "quantity": 10,
        "price": {"id": "-1"},
        "rate": 99.99
      },
      {
        "item": {"id": "789"},
        "quantity": 5,
        "price": {"id": "-1"},
        "rate": 49.99
      }
    ]
  },
  "customFieldList": {
    "customField": [
      {
        "scriptId": "custbody_source_system",
        "value": "Shopify"
      }
    ]
  }
}

Response (201 Created):
{
  "id": "12345",
  "tranId": "SO-12345",
  "links": [...]
}

Search with SuiteQL

POST /services/rest/query/v1/suiteql
Authorization: Bearer {access_token}
Content-Type: application/json
Prefer: transient

{
  "q": "SELECT id, companyName, email, balance
        FROM customer
        WHERE balance > 1000
        AND isinactive = 'F'
        ORDER BY balance DESC"
}

Response:
{
  "links": [...],
  "count": 45,
  "hasMore": true,
  "offset": 0,
  "totalResults": 156,
  "items": [
    {"id": "101", "companyName": "Big Co", "email": "...", "balance": 50000},
    {"id": "205", "companyName": "Medium Inc", "email": "...", "balance": 25000},
    ...
  ]
}

// Pagination: Add ?offset=100&limit=100 to URL

Rate Limits and Best Practices

RATE LIMIT HANDLING (Exponential Backoff)
═══════════════════════════════════════════════════════════════════

async function callWithRetry(apiCall, maxRetries = 5) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await apiCall();
      return response;
    } catch (error) {
      if (error.status === 429) { // Rate limited
        const waitTime = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s, 8s, 16s
        console.log(`Rate limited. Waiting ${waitTime}ms`);
        await sleep(waitTime);
      } else {
        throw error; // Non-retryable error
      }
    }
  }
  throw new Error('Max retries exceeded');
}

SOAP vs REST Decision

SOAP Endpoint Configuration

SOAP WSDL ENDPOINTS
═══════════════════════════════════════════════════════════════════

Current Version (2024.1):
https://{account_id}.suitetalk.api.netsuite.com/wsdl/v2024_1_0/netsuite.wsdl

Endpoint URL:
https://{account_id}.suitetalk.api.netsuite.com/services/NetSuitePort_2024_1

Account ID Format:
- Production: 1234567 (numeric)
- Sandbox: 1234567_SB1

Headers Required:
┌─────────────────────────────────────────────────────────────────┐
│ <tokenPassport>                                                 │
│   <account>{account_id}</account>                               │
│   <consumerKey>{consumer_key}</consumerKey>                     │
│   <token>{token_id}</token>                                     │
│   <nonce>{random_string}</nonce>                                │
│   <timestamp>{unix_timestamp}</timestamp>                       │
│   <signature algorithm="HMAC-SHA256">{signature}</signature>    │
│ </tokenPassport>                                                │
└─────────────────────────────────────────────────────────────────┘

SOAP Operation Examples

Add Customer (Single)

<add>
  <record xsi:type="Customer">
    <companyName>Acme Corporation</companyName>
    <email>info@acme.com</email>
    <phone>555-1234</phone>
    <subsidiary internalId="1"/>
    <customFieldList>
      <customField xsi:type="StringCustomFieldRef" scriptId="custentity_source">
        <value>API</value>
      </customField>
    </customFieldList>
  </record>
</add>

Add List (Bulk)

<addList>
  <record xsi:type="Customer">
    <companyName>Customer 1</companyName>
    <subsidiary internalId="1"/>
  </record>
  <record xsi:type="Customer">
    <companyName>Customer 2</companyName>
    <subsidiary internalId="1"/>
  </record>
  <!-- Up to 100 records per call -->
</addList>

Response:
<addListResponse>
  <writeResponseList>
    <writeResponse>
      <status isSuccess="true"/>
      <baseRef internalId="12345" type="customer"/>
    </writeResponse>
    <writeResponse>
      <status isSuccess="false">
        <statusDetail type="ERROR">
          <code>DUP_ENTITY</code>
          <message>Duplicate entity name</message>
        </statusDetail>
      </status>
    </writeResponse>
  </writeResponseList>
</addListResponse>

Search with Pagination

<!-- Initial Search -->
<search>
  <searchRecord xsi:type="CustomerSearchBasic">
    <lastModifiedDate operator="onOrAfter">
      <searchValue>2024-01-01T00:00:00</searchValue>
    </lastModifiedDate>
  </searchRecord>
</search>

<!-- Response includes searchId for pagination -->
<searchResponse>
  <searchResult>
    <status isSuccess="true"/>
    <totalRecords>1500</totalRecords>
    <pageSize>1000</pageSize>
    <totalPages>2</totalPages>
    <pageIndex>1</pageIndex>
    <searchId>WEBSERVICES_1234567_12012024...</searchId>
    <recordList>...</recordList>
  </searchResult>
</searchResponse>

<!-- Get Next Page -->
<searchMoreWithId>
  <searchId>WEBSERVICES_1234567_12012024...</searchId>
  <pageIndex>2</pageIndex>
</searchMoreWithId>

Integration Architecture

SHOPIFY ↔ NETSUITE DATA FLOWS
═══════════════════════════════════════════════════════════════════

ORDERS (Shopify → NetSuite)
┌─────────────┐    Webhook     ┌─────────────┐    Create    ┌─────────────┐
│   Shopify   │ ────────────→  │  Middleware │ ──────────→  │  NetSuite   │
│   Order     │                │  (Celigo)   │              │ Sales Order │
└─────────────┘                └─────────────┘              └─────────────┘

Mapping:
  Shopify Order → NetSuite Sales Order
  Shopify Line Items → SO Line Items
  Shopify Customer → NS Customer (match or create)
  Shopify Shipping → NS Shipping Item
  Shopify Discount → NS Discount Item or Price Adjustment

INVENTORY (NetSuite → Shopify)
┌─────────────┐   Scheduled   ┌─────────────┐    Update    ┌─────────────┐
│  NetSuite   │ ───────────→  │  Middleware │ ──────────→  │   Shopify   │
│  Inventory  │    Sync       │             │              │  Inventory  │
└─────────────┘               └─────────────┘              └─────────────┘

Sync frequency: Every 15 min (typical)
Source: Available quantity from NS locations
Target: Shopify inventory levels by location

PRODUCTS (NetSuite → Shopify)
┌─────────────┐   On Change   ┌─────────────┐    Create/   ┌─────────────┐
│  NetSuite   │ ───────────→  │  Middleware │ ──────────→  │   Shopify   │
│    Item     │               │             │    Update    │   Product   │
└─────────────┘               └─────────────┘              └─────────────┘

Mapping:
  NS Item → Shopify Product
  NS Matrix Item → Shopify Variants
  NS Pricing → Shopify Price
  NS Images → Shopify Images

Order Sync Configuration

Common Integration Challenges

Challenge: SKU/Item Matching

ITEM MATCHING STRATEGY
═══════════════════════════════════════════════════════════════════

Priority Order:
1. Exact SKU match (Shopify SKU = NS Item Name/SKU)
2. UPC/Barcode match
3. Shopify Product ID → NS custom field
4. Manual mapping table

NetSuite Custom Fields:
  custitem_shopify_product_id   - Shopify product ID
  custitem_shopify_variant_id   - Shopify variant ID

Lookup Logic:
  IF item found by SKU → use
  ELSE IF item found by UPC → use
  ELSE IF mapping exists → use mapped item
  ELSE → create integration error, flag for review

Challenge: Customer Deduplication

CUSTOMER MATCHING STRATEGY
═══════════════════════════════════════════════════════════════════

Match Hierarchy:
1. custentity_shopify_customer_id (if returning customer)
2. Email address (primary match)
3. Phone number (secondary)
4. Name + Address (fuzzy match - risky)

Recommendation:
- Match on email first
- If no match, create new customer
- Store Shopify customer ID on NS customer
- Let customer merge handle duplicates later

Guest Checkout Handling:
- Create customer with email OR
- Use generic "Web Customer" with order details

Integration Scenarios

Data Flow Architecture

SALESFORCE ↔ NETSUITE QUOTE-TO-CASH
═══════════════════════════════════════════════════════════════════

OPPORTUNITY TO ORDER FLOW:

Salesforce                  Middleware              NetSuite
┌──────────────┐           ┌──────────────┐        ┌──────────────┐
│  Opportunity │           │              │        │              │
│  Created     │           │              │        │   Customer   │
│      ↓       │           │              │        │   (verify)   │
│  Account     │ ────────→ │  Map/        │ ─────→ │      ↓       │
│  Sync        │           │  Transform   │        │   Estimate   │
│      ↓       │           │              │        │      ↓       │
│  Quote       │ ────────→ │              │ ─────→ │  Sales Order │
│  Created     │           │              │        │      ↓       │
│      ↓       │           │              │        │   Invoice    │
│  Closed-Won  │ ────────→ │              │ ─────→ │      ↓       │
└──────────────┘           └──────────────┘        │   Payment    │
                                                   └──────────────┘
                                    │
                                    ↓
                           ┌──────────────┐
                           │  Invoice     │
                           │  Status      │
                           │  Back to SF  │
                           └──────────────┘

ID MAPPING (Critical):
  SF Account ID    ↔  NS Customer (external ID or custom field)
  SF Contact ID    ↔  NS Contact (external ID)
  SF Opportunity   ↔  NS Sales Order (custom field)
  SF Product ID    ↔  NS Item (external ID or SKU)

Field Mapping: Account to Customer

Integration Patterns

Pattern: Closed-Won → Sales Order

TRIGGER: Opportunity.Stage = 'Closed Won'
═══════════════════════════════════════════════════════════════════

Process Flow:
1. SF sends webhook or middleware polls for Closed-Won opps
2. Middleware retrieves full opportunity with line items
3. Map SF Account → NS Customer (create if needed)
4. Map SF Products → NS Items
5. Create Sales Order in NetSuite
6. Store NS SO internal ID back on SF Opportunity
7. If error, create integration error record for review

Error Handling:
  - Item not found → Flag opportunity, notify sales
  - Customer create fails → Log error, retry with manual review
  - Order validation fails → Return validation errors to SF

Idempotency:
  - Check if SO already exists (by SF Opp ID)
  - If exists, update instead of create
  - Prevent duplicate orders on webhook retries

Marketplace Integration Overview

Amazon Seller Central Flow

AMAZON SELLER CENTRAL ↔ NETSUITE
═══════════════════════════════════════════════════════════════════

ORDER FLOW:
Amazon              Middleware           NetSuite
┌──────────┐       ┌──────────┐         ┌──────────┐
│  Order   │ ────→ │ Polling  │ ──────→ │  Sales   │
│  Created │       │ or Push  │         │  Order   │
└──────────┘       └──────────┘         └──────────┘
                                              │
                                              ↓
                                        ┌──────────┐
                                        │  Item    │
                                        │ Fulfill  │
                                        └──────────┘
                                              │
                   ┌──────────┐               ↓
                   │ Shipment │ ←────── ┌──────────┐
                   │ Confirm  │         │ Tracking │
                   └──────────┘         └──────────┘

INVENTORY FLOW:
NetSuite                 Middleware              Amazon
┌──────────┐            ┌──────────┐           ┌──────────┐
│ Available │ ────────→ │ Calculate │ ───────→ │ Inventory│
│ Quantity  │           │ Available │          │  Feed    │
└──────────┘            │ for Amazon│          └──────────┘
                        └──────────┘

Available = On Hand - Committed - Safety Stock - Other Channels

FBA (Fulfillment by Amazon):
- Track FBA inventory as separate NS location
- Receive inbound shipments as transfers TO FBA location
- Sales from FBA = transfers FROM FBA location
- Or use FBA receipts from settlement reports

Multi-Channel Inventory Strategy

INVENTORY ALLOCATION STRATEGY
═══════════════════════════════════════════════════════════════════

Total Available in NetSuite: 1000 units

Channel Allocation:
┌─────────────────────────────────────────────────────────────────┐
│ Channel          │ % Allocation │ Units │ Buffer │ Advertised  │
├─────────────────────────────────────────────────────────────────┤
│ Website (Shopify)│     40%      │  400  │   20   │    380      │
│ Amazon           │     30%      │  300  │   15   │    285      │
│ eBay             │     15%      │  150  │   10   │    140      │
│ Walmart          │     10%      │  100  │   10   │     90      │
│ Reserve/Safety   │      5%      │   50  │    -   │      -      │
└─────────────────────────────────────────────────────────────────┘

Buffer = Safety stock per channel to prevent oversell

Dynamic Reallocation:
- If Amazon inventory < 50 and Website > 200
- Reallocate 50 units from Website to Amazon
- Prevents stockouts on high-velocity channels

Implementation:
- Custom NetSuite saved search for available by location
- Scheduled script to calculate and push to channels
- Or use channel management tool (ChannelAdvisor, etc.)

Common EDI Documents

EDI Architecture

EDI ARCHITECTURE OPTIONS
═══════════════════════════════════════════════════════════════════

OPTION 1: VAN (Value-Added Network)
Trading Partner → VAN → EDI Translator → NetSuite
                 (SPS, TrueCommerce)

Pros: Managed connectivity, compliance monitoring
Cons: Per-document fees, VAN dependency

OPTION 2: Direct (AS2)
Trading Partner → AS2 Gateway → EDI Translator → NetSuite

Pros: No per-document fees, lower long-term cost
Cons: Manage own connectivity, higher setup

TYPICAL EDI STACK FOR NETSUITE:
┌─────────────────────────────────────────────────────────────────┐
│ Trading Partner                                                 │
│       ↓ EDI X12                                                 │
│ ┌─────────────────┐                                             │
│ │ VAN / AS2       │  SPS Commerce, TrueCommerce, etc.          │
│ └─────────────────┘                                             │
│       ↓ XML/JSON                                                │
│ ┌─────────────────┐                                             │
│ │ EDI Translator  │  Built into VAN or separate (Dell Boomi)   │
│ └─────────────────┘                                             │
│       ↓ NetSuite format                                         │
│ ┌─────────────────┐                                             │
│ │ Integration     │  SuiteApp, Celigo, or custom RESTlet       │
│ └─────────────────┘                                             │
│       ↓                                                         │
│ ┌─────────────────┐                                             │
│ │ NetSuite        │                                             │
│ └─────────────────┘                                             │
└─────────────────────────────────────────────────────────────────┘

EDI Implementation Checklist

Platform Comparison

Celigo integrator.io Overview

CELIGO ARCHITECTURE
═══════════════════════════════════════════════════════════════════

┌─────────────────────────────────────────────────────────────────┐
│ CELIGO INTEGRATOR.IO                                            │
│                                                                 │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │   FLOWS     │   │   IMPORTS   │   │   EXPORTS   │           │
│  │ (workflows) │   │ (to NS)     │   │ (from NS)   │           │
│  └─────────────┘   └─────────────┘   └─────────────┘           │
│         │                │                   │                  │
│         ↓                ↓                   ↓                  │
│  ┌───────────────────────────────────────────────────┐         │
│  │              MAPPING / TRANSFORMATION              │         │
│  │    Handlebars templates, lookups, defaults        │         │
│  └───────────────────────────────────────────────────┘         │
│                          │                                      │
│                          ↓                                      │
│  ┌───────────────────────────────────────────────────┐         │
│  │              ERROR HANDLING                        │         │
│  │    Retry, manual resolution, alerts               │         │
│  └───────────────────────────────────────────────────┘         │
│                          │                                      │
│                          ↓                                      │
│  ┌───────────────────────────────────────────────────┐         │
│  │              MONITORING / LOGGING                  │         │
│  │    Dashboard, audit trail, notifications          │         │
│  └───────────────────────────────────────────────────┘         │
└─────────────────────────────────────────────────────────────────┘

KEY CONCEPTS:
  Flow: End-to-end integration (e.g., Shopify Order → NS SO)
  Export: Pull data from source system
  Import: Push data to destination system
  Lookup: Reference data resolution (e.g., customer match)
  Mapping: Field-by-field transformation

PRE-BUILT INTEGRATION APPS:
  - Shopify - NetSuite
  - Salesforce - NetSuite
  - Amazon - NetSuite
  - 3PL/WMS - NetSuite
  - Many more on Celigo marketplace

Middleware Selection Criteria

Design Principles

INTEGRATION DESIGN PRINCIPLES
═══════════════════════════════════════════════════════════════════

1. IDEMPOTENCY
   - Same request twice = same result
   - Use external IDs to prevent duplicates
   - Check-before-create pattern

   Example:
   if (existingRecord = findByExternalId(externalId)) {
     return update(existingRecord);
   } else {
     return create(newRecord);
   }

2. ERROR HANDLING
   - Assume failures will happen
   - Log everything (request, response, errors)
   - Implement retry with exponential backoff
   - Alert on repeated failures

3. DATA VALIDATION
   - Validate at source before sending to NS
   - Fail fast with clear error messages
   - Don't rely on NS validation alone

4. MONITORING
   - Track success/failure rates
   - Monitor latency
   - Set up alerts for anomalies
   - Review logs regularly

5. SCALABILITY
   - Design for 10x current volume
   - Use async processing where possible
   - Batch operations when appropriate
   - Respect rate limits

External ID Strategy

EXTERNAL ID BEST PRACTICES
═══════════════════════════════════════════════════════════════════

What is External ID?
- Unique identifier from source system
- Stored on NetSuite record
- Enables upsert (update if exists, insert if new)
- Prevents duplicates

Format Recommendations:
  [SOURCE]_[ID]

  Examples:
  - SF_0015000000abcDE     (Salesforce Account)
  - SHOP_12345678          (Shopify Order)
  - AMZ_113-1234567-1234567 (Amazon Order)

Implementation:
  // REST API - use externalId in URL
  PUT /services/rest/record/v1/customer/eid:SF_0015000000abcDE

  // SOAP - upsert operation
  <upsert>
    <record xsi:type="Customer" externalId="SF_0015000000abcDE">
      <companyName>Updated Name</companyName>
    </record>
  </upsert>

Custom Field Alternative:
  If externalId field unavailable, use custom field:
  custentity_source_system_id

  Search before create:
  1. Search by custom field
  2. If found, update
  3. If not found, create with custom field set

Error Handling Patterns

Integration Testing Checklist

Go-Live Checklist