Customer and Company Integrations

This page describes best practices for integrating customer and company data between Norce Commerce and external systems such as ERP or CRM. It covers integration patterns, API usage, and recommended approaches for handling customer and company entities.

For a detailed explanation of the Customer and Company data model — fields, relationships, identification keys, and import behavior — see The Customer and Company Model.

Integration Overview

Integrating customers and companies between Norce Commerce and other systems can vary depending on business needs. The following best practices assume:

• The client sells to both consumers and businesses.
• Order history is synchronized from the ERP to ecommerce applications.
• End customers can log in and update their information via a "My Pages" site connected to Norce Commerce.

Customer Integration Process

The diagrams below illustrate the four main customer integration flows.

1. New customer order — create customer in ERP

2. New or changed customers in ERP — update CustomerCode in Norce

3. Customer changes in storefront — passed on to ERP

4. Scheduled sync from ERP — keeping customer data up to date in Norce

Key Steps in the Integration Process

1. New customer order — create customer in ERP:
   When a new order is received, the integration checks whether the customer already has an ERP code. If not, the customer or company is created in the ERP.

2. New or changed customers in ERP — update CustomerCode in Norce:
   When a customer or company is created or updated in the ERP, the integration pushes the ERP code and key fields to Norce Commerce using ImportCustomers or ImportCompanies.

3. Customer changes in storefront — passed on to ERP:
   When a customer or company with an existing ERP code updates their information in the frontend, the integration listens to CustomerChangeNotification and CompanyChangeNotification events, fetches the updated data via Norce Commerce Query, and sends it to the ERP.

4. Scheduled synchronization — keeping customer data up to date in Norce:
   As a fail-safe, a scheduled job fetches all customers from the ERP and updates the customer/company code in Norce Commerce. The integration calls ImportCustomers and ImportCompanies, sending minimal information and the ERP code.

Norce Commerce APIs for Integration

Norce Commerce provides several APIs for system integration:

• Norce Commerce Connect:
  Used for all system integrations. See Calling Norce Commerce Connect.

• Norce Commerce Query:
  Used to look up and fetch data. See Calling Norce Commerce Query.

• Norce Commerce Event:
  Used for event-driven integrations. See Using Norce Commerce Event.

Customer and Company Entities

In Norce Commerce, Customer (individuals) and Company (organizations) are separate entities with relationships (e.g., organization-contacts). If your ERP does not separate them, the integration must handle mapping.

• Use the Code field in Norce Commerce as the external identifier (typically the ERP customer number or CRM ID).
• The Id field is Norce's internal identifier and should only be used for matching back to Norce.

Application and Client Uniqueness

Norce Commerce can be configured in two ways:

1. Application-unique customers/companies:
   The same entity can have different codes in different applications.
2. Client-unique customers/companies:
   The same entity can create orders across multiple applications.

Integration setup should reflect this configuration.

Importing Customers

To update customers in Norce Commerce, use the ImportCustomers API. This is an asynchronous operation; a job ID is returned for tracking.

• See System integration patterns for more on asynchronous integration.

Customer Object Details

• Full Customer schema

Important fields:

• Code: External identifier (ERP/CRM).
• Id: Norce internal identifier (for Norce use only).
• EmailAddress: Use as unique identifier if Code is not set.
• ApplicationKey: Relates customer to an application; if null, shared across all applications.

Important relationships:

• Accounts: For login functionality (one per application).
• Companies: If the customer is a contact for an organization.
• PriceLists: If the customer has custom prices or assortments.

Import Frequency

Most integrations use delta imports (changes only), typically once per day. Full imports are rare.

Note: GDPR and anonymization features can automatically scramble customer data. Consider this when setting up integration.

Importing Companies

To update companies, use the ImportCompanies API. This is also asynchronous and returns a job ID.

• See System integration patterns for more on asynchronous integration.

Company Object Details

• Full Company schema

Important fields:

• Code: External identifier (ERP/CRM).
• Id: Norce internal identifier (read-only).
• OrganizationNo: Use as unique identifier if Code is not set.

Important relationships:

• Customers: List of contacts with full information.
• Contacts: List of contacts by code (customer must exist in Norce).
• PriceLists: For company-specific prices or assortments.

Import Frequency

Most integrations use delta imports (changes only), typically once per day.

Event Types for Integration

Norce Commerce Event provides notifications for changes to customers and companies.

CustomerChangedNotification

• Notifies when a customer is changed.
• Listen to this event, fetch the customer using Norce Commerce Query, and update external systems.
• Administering Event types
• Customer entity in Query API

CompanyChangedNotification

• Notifies when a company is changed.
• Listen to this event, fetch the company using Norce Commerce Query, and update external systems.
• Administering Event types
• Company entity in Query API

Further Reading and Examples

• Norce Commerce Query:
  • Calling Norce Commerce Query
  • Customer lookups (Postman)
  • Company lookups (Postman)
• Norce Commerce Event:
  • Using Storm Event
• Norce Commerce Connect:
  • Calling Norce Commerce Connect
• Integration Examples:
  • Connect Postman examples
  • Code examples for Customer integration