Shopify–NetSuite Customers & Addresses Integration

Introduction

When integrating Shopify with NetSuite, one of the first challenges you’ll face is managing customers and addresses.

Every order in Shopify is tied to a customer — and that customer may:

• Already exist in NetSuite.
• Have multiple addresses.
• Place guest checkouts without creating an account.

If you don’t sync customer data properly, you’ll face:

• Duplicate customer records.
• Wrong address assignments.
• Failed order imports because of missing relationships.

This guide is a deep dive into handling Shopify customers and addresses in NetSuite. We’ll cover:

• Customer record structures in Shopify vs. NetSuite.
• Mapping fields between both systems.
• Handling guest checkouts.
• Managing multiple addresses.
• Avoiding duplicates with deduplication rules.
• Advanced strategies for B2C vs. B2B.

1. Understanding Customer Records in Shopify

Shopify stores customers in a relatively simple structure:

1.1. Shopify Customer Object (simplified)

Key fields include:

• id → Unique Shopify customer ID.
• email → Email address (primary identifier).
• first_name, last_name.
• phone.
• tags → Useful for segmentation.
• default_address.
• addresses[] → Array of multiple saved addresses.

👉 Example JSON snippet:

{
  "id": 56473829,
  "email": "jane.doe@gmail.com",
  "first_name": "Jane",
  "last_name": "Doe",
  "phone": "+1-416-555-1212",
  "default_address": {
    "id": 11223344,
    "address1": "123 Queen Street",
    "city": "Toronto",
    "province": "Ontario",
    "country": "Canada",
    "zip": "M5H 2N2"
  },
  "addresses": [
    {
      "id": 11223344,
      "address1": "123 Queen Street",
      "city": "Toronto",
      "province": "Ontario",
      "country": "Canada",
      "zip": "M5H 2N2"
    },
    {
      "id": 55667788,
      "address1": "456 King Street",
      "city": "Toronto",
      "province": "Ontario",
      "country": "Canada",
      "zip": "M5V 3L9"
    }
  ]
}

2. Understanding Customer Records in NetSuite

NetSuite’s customer record is more complex and flexible.

2.1. Key Fields in NetSuite Customer Record

• Entity ID → Display name (often “Firstname Lastname”).
• Email → Must be unique.
• Phone.
• Subsidiary → Important if you run multi-company.
• Currency → If using multi-currency customers.
• Addresses → Stored as subrecords in the Address Book.

👉 NetSuite allows:

• Multiple shipping and billing addresses.
• One address to be marked as “Default Shipping” or “Default Billing”.
• Customers to belong to segments (e.g., B2B customers with terms).

3. Mapping Customers Between Shopify & NetSuite

The core of integration is field mapping.

3.1. Basic Field Mapping

3.2. Example: Creating a Customer in NetSuite from Shopify

If customer doesn’t exist:

1. Check if email already exists in NetSuite.
2. If not found → create new Customer record.
3. Add default address from Shopify.
4. Save Shopify ID into custom field (custentity_shopify_id).

👉 Example RESTlet pseudocode (SuiteScript 2.1):

define(['N/record'], function(record) {
   function createCustomer(data) {
      var customer = record.create({ type: record.Type.CUSTOMER });
      customer.setValue({ fieldId: 'entityid', value: data.first_name + ' ' + data.last_name });
      customer.setValue({ fieldId: 'email', value: data.email });
      customer.setValue({ fieldId: 'phone', value: data.phone });
      customer.setValue({ fieldId: 'custentity_shopify_id', value: data.id });

      var subrecord = customer.getSublistSubrecord({ sublistId: 'addressbook', fieldId: 'addressbookaddress', line: 0 });
      subrecord.setValue({ fieldId: 'addr1', value: data.default_address.address1 });
      subrecord.setValue({ fieldId: 'city', value: data.default_address.city });
      subrecord.setValue({ fieldId: 'zip', value: data.default_address.zip });

      var id = customer.save();
      return id;
   }
   return { post: createCustomer };
});

4. Handling Guest Checkouts

Shopify allows guest checkout (no customer account).

Best Practice

• Create a NetSuite customer record with email as identifier.
• If no email exists → create “Guest” customer (e.g., Guest_Order_12345).
• Use Shopify order number as reference.

5. Deduplication Strategies

Without rules, duplicates pile up fast.

5.1. Deduplication Keys

• Primary Key: Email address.
• Secondary Key: Phone number.
• Fallback: Shopify customer ID stored in custom field.

5.2. Deduplication Workflow

1. Incoming Shopify order → check if email exists in NetSuite.
2. If found → attach order to existing customer.
3. If not found → create new customer.
4. If email blank → create “Guest Checkout” customer.

6. Handling Multiple Addresses

6.1. Shopify Model

• Customers can save multiple addresses.
• Each order uses one shipping address and one billing address.

6.2. NetSuite Model

• Address Book supports multiple addresses with flags:
  • Default Shipping
  • Default Billing

6.3. Mapping Rules

• Shopify default_address → NetSuite Default Shipping + Billing.
• New Shopify addresses → add new entries in NetSuite Address Book.
• Avoid duplicates by comparing:
  • Street + City + Postal + Country.

7. Custom Fields and Tags

Shopify allows tags, which can be very powerful when passed to NetSuite.

Examples:

• Tag = “VIP” → NetSuite field custentity_vip_customer = T.
• Tag = “Wholesale” → NetSuite customer type = Wholesale.

👉 This allows marketing and reporting alignment.

8. B2C vs. B2B Considerations

• B2C (retail):
  • One person = one customer.
  • Use email as key.
• B2B (wholesale Shopify store):
  • Multiple buyers may place orders under same business.
  • Map Shopify Company record → NetSuite Parent Customer.
  • Buyers become child contacts.

9. Common Errors & Fixes

10. Testing Strategy

Before going live:

• ✅ Import 10 sample customers (with multiple addresses).
• ✅ Import 5 guest checkouts.
• ✅ Update an existing Shopify customer → confirm NetSuite update.
• ✅ Place orders for existing + new customers.
• ✅ Confirm address sync works in both directions.

11. Best Practices

• Always use Shopify ID in a custom NetSuite field for traceability.
• Deduplicate customers by email + phone.
• Sync addresses incrementally, not overwrite.
• Map tags into NetSuite fields for reporting.
• Use error logging: track failed customer syncs.

12. How Does Shopify Push Customer Data to NetSuite?

Shopify itself doesn’t natively “push” data to NetSuite — instead, you build (or use a connector) that listens to Shopify events and then calls NetSuite APIs.

12.1. Using Shopify Webhooks

Shopify offers webhooks that notify your integration whenever something happens, such as:

• customers/create → Fires when a new customer is created.
• customers/update → Fires when customer details change.
• orders/create → Fires when a new order is placed (with embedded customer info).

👉 Flow:

1. Customer signs up or places an order in Shopify.
2. Shopify sends a webhook JSON payload to your integration service (e.g., AWS Lambda, Boomi, Celigo, middleware).
3. That service transforms the payload into NetSuite format.
4. The service calls NetSuite via RESTlet or REST Web Services.
5. NetSuite creates/updates the Customer record.

12.2. Direct API Polling (less efficient)

• Alternative approach: your integration polls Shopify Admin API every few minutes to fetch new/updated customers.
• Example: GET /admin/api/2025-01/customers.json?updated_at_min=2025-01-01T00:00:00Z
• Drawback: Uses API quota, slower than real-time.
• Best practice: Use webhooks → fallback to polling if webhook fails.

13. Authentication Methods for Shopify → NetSuite

When pushing data into NetSuite, the integration must authenticate. NetSuite offers several authentication methods:

13.1. Token-Based Authentication (TBA) – Recommended

• Uses Consumer Key, Consumer Secret, Token ID, Token Secret.
• Works without storing usernames/passwords.
• More secure (revocable per role).
• Industry best practice for system-to-system integration.

👉 Best for Shopify integrations.

How it works:

1. Shopify webhook → AWS Lambda.
2. Lambda generates OAuth 1.0 signed request with TBA credentials.
3. Lambda calls NetSuite RESTlet → Customer record created.

Example request header:

Authorization: OAuth 
oauth_consumer_key="your_consumer_key",
oauth_token="your_token_id",
oauth_signature_method="HMAC-SHA256",
oauth_timestamp="1616432764",
oauth_nonce="a8c0d2e1",
oauth_version="1.0",
oauth_signature="base64signature"

13.2. OAuth 2.0

• NetSuite REST Web Services (2021.1+) supports OAuth 2.0.
• More modern, compatible with identity providers.
• Slightly more setup overhead.
• Rarely used in Shopify direct-to-NetSuite flows (but possible).

13.3. User/Password (Deprecated – Not Recommended)

• Old method using NetSuite credentials.
• Risky, not secure.
• Disabled in many accounts unless specifically enabled.

👉 Avoid for all new integrations.

14. Putting It All Together: Shopify → NetSuite Customer Flow

Step-by-step real example (using TBA + RESTlet):

1. Event in Shopify:
   A new customer registers:
   { “id”: 99887766, “email”: “john.doe@gmail.com”, “first_name”: “John”, “last_name”: “Doe”, “phone”: “+1-212-555-1212”, “default_address”: { “address1”: “10 Broadway Ave”, “city”: “New York”, “province”: “NY”, “zip”: “10001”, “country”: “United States” } }
2. Webhook Trigger:
   Shopify sends JSON payload to your endpoint (e.g., https://api.mycompany.com/shopify/customers).
3. Transformation Layer:
   Middleware maps fields → NetSuite format.
   • email → email
   • first_name + last_name → entityid
   • default_address → Address Book subrecord
4. Authentication:
   Middleware signs request with TBA credentials.
5. Push to NetSuite (RESTlet example): POST https://<account_id>.suitetalk.api.netsuite.com/app/site/hosting/restlet.nl?script=123&deploy=1
6. NetSuite Creates Record:
   Customer created → ID returned → middleware stores mapping.

15. Hybrid Push + Pull Approach

Some businesses prefer:

• Push via Webhook (real-time).
• Pull via Scheduled Job (nightly sync to reconcile missed data).

👉 Best practice for reliability: “Event-driven + scheduled reconciliation”.

16. Key Takeaways on Push + Authentication

• Shopify can push data using webhooks, or pull using Admin API.
• NetSuite accepts data via:
  • RESTlets (with Token-Based Authentication) – most common.
  • REST Web Services (with OAuth 2.0) – modern alternative.
• Token-Based Authentication (TBA) is the recommended method for Shopify → NetSuite customer integration.
• Always combine event-driven + scheduled sync for safety.

Updated Summary (with Authentication)

In this page, you’ve learned how to integrate Shopify Customers & Addresses with NetSuite:

• How customer records differ in both systems.
• Field mapping strategies (emails, addresses, tags).
• Deduplication rules and guest checkout handling.
• Multi-address handling in NetSuite Address Book.
• How Shopify actually pushes customer data using webhooks.
• Which authentication method to use (TBA recommended).

👉 Next in the series: Shopify–NetSuite Products & Variants Integration