Bring Your Own CRM or CDP

Many NewStore customers leverage an external CRM or CDP to store and enrich customer profile data. If this external tool acts as your source of truth for customer metadata you may wish to leverage it directly as the source of customer data for operations across the NewStore platform. This is commonly referred to as Bring Your Own (BYO) CRM.

NewStore offers the configuration of external APIs such that calls to our Customer API are re-routed to your customer repository instead of our default built-in Customer Profiles. This means that NewStore does not store a copy of customer profiles and does not need to be kept in sync with your external source of truth, since we always go directly to the source for requests.

Important

By using an external CRM you must return customer metadata and error data according to a strict format as defined in the documentation. It will be the responsibility of the external service and those building the integration to ensure the scalability and performance of any solution leveraging the APIs.

     

Configuration overview

There are two steps to integrate an external source of truth:

1. The external APIs receiving redirected requests must be implemented in accordance with our API specifications. Any external system deviating from the specifications will be filtered out by the NewStore platform.

2. Connect your external APIs to the NewStore platform by providing their URL, authentication key, and by finally enabling the feature.

The following is an example on how a “Get Customer Profile by Id” request is routed through the system and reaches your integration:

GET /customers/profiles/{id} 

• When a request origin makes a v2 Customer Profiles API call it must follow our API requirements.

• Successful calls will be redirected to the external CRM configured. In this example it will be redirected to: {URL}/{id}

• Your integration is expected to respond with the correct metadata and format based upon the request. Deviation from the specifications will result in an error returned to the request origin.

                     Customer Profile v2 API calls are redirected to your integration based upon the domain provided and the expected path in the technical spec.

Step 1: Building the external CRM APIs

In order to ensure a modular “plug-and-play” approach it is essential that services depending on the customer metadata are unaffected by the choice to use our internal solution or an external one. To achieve this, external configurations must mimic the expected input & output formats of our existing Customer Profile v2 APIs.

To facilitate building your external CRM APIs we provide a technical spec and details of all Customer Profile v2 APIs which are mandatory. A “Mandatory” status means that your external CRM is expected to handle redirected calls to that endpoint and will cause significant issues otherwise.

See the table below for details on the mandatory endpoints, and the separate API Specifications Documentation for the external integration spec.

Step 2: Connect your external APIs to NewStore

Configuration of the external APIs includes setting a URL, an authentication token, and a feature flag to enable redirecting requests. This is done through a self-service API endpoint:

PATCH https://[tenant].newstore.net/customer/config

{
  "byo_crm": {
    "api_token": "some-token"
    "url": "https://example.com/customer"
    "enabled": true,
  }
}

The URL is used to identify the domain of your APIs and will be used as the base of all API requests being forward to your external solution.

Example: If your base URL is https://external.crm/ then we will automatically assume we fetch a profile through the https://external.crm/{id} endpoint. This follows a {URL}/{path per endpoint} model detailed in the spec.

Authentication is currently through long lived keys you set through the self-service API endpoint above. In this way you are able to control invalidation and creation of keys as necessary. It is the responsibility of the external implementation to protect its data and validate all incoming requests for the appropriate authentication & authorization.

You may check the current state of configuration settings any time using:

GET  https://[tenant].newstore.net/customer/config

{
  "byo_crm": {
    "api_token": "some-token"
    "url": "https://example.com/customer"
    "enabled": true,
  }
}

Important

These properties can and should be set by environment. We recommend testing thoroughly in Sandbox and Staging environments before finally enabling your Production tenant.

Customer APIs to External APIs Mapping

These mappings are to help provide an overview of which Customer Profile v2 APIs are mandatory when configuring your external source of truth:

Important additions and FAQ

Unique and consistent customer IDs

It is critical that the external CRM provides a consistent and unique identifier for each customer. The external CRM is considered to be the source of truth and this identifier will be used across the NewStore platform, from Order Management, to Clienteling, to help tie all elements of a customer together under one unique id. Customer IDs must not contain Personally Identifiable Information (PII) such as emails.

Required customer metadata

NewStore uses the shopper email address as a required field when creating a new customer. This is currently the only required field that is supported in the Associate App. If an external CRM attempts to require other properties for profile creation they will not be reflected in the Associate App as such.

External CRMs may enforce custom required fields in their customer creation flows by denying requests missing their desired data. Errors returned from the external CRM will be passed through back to the origin in accordance with the rules as described in “Error Cases” below.

Integration health & performance expectations

The external service is responsible for enabling real-time alerting and analysis for health and performance monitoring. NewStore will not be able to provide health metrics or alarms for external CRMs as these services are external to our platform. 

NewStore recommends any configured external CRM to be able to handle expected traffic volume with a <300ms response time for 95% of requests. Requests that take longer than 3s will result in a timeout error.

Please ensure that proper tracking is in place to swiftly remedy issues that arise with integrations to NewStore.

Anonymous checkout/orders

Anonymous workflows do not make requests to the Customer Profiles and so BYO CRM will not be impacted.

Right to be forgotten/deletion requests

NewStore offers a Profile Deletion Request API which allows customers to request deletion of shopper data in our platform. NewStore will not delete customer data in your external CRM, and will not forward this API call to your systems. External systems are expected to manage their responsibilities with respect to deleting data separately.

Using extended attributes for custom properties

CRMs are often well known for data extensibility allowing users to specify many types of additional custom properties and values that can be populated on entries. If you would like to expose these properties in the Associate App you may do so by leveraging the NewStore Extended Attributes and Custom Widget functionality.

NewStore customer profiles future development

The NewStore Customer APIs will offer additional functionality and endpoints over time. In these cases, new end points and properties (non-breaking changes) may be added to the existing API. These features will be unavailable while an external CRM integration has not adopted the necessary changes to support them, however the existing functionality will not break.

It is the responsibility of the integration manager to adopt and support new endpoints and new functionality as desired. Please see our general API guidelines for more information on how we support our APIs.

EventStream with an External CRM

The NewStore EventStream will not emit CRM related events when an External CRM is being used. If infrastructure or other partner integrations require updates based on changes to customer metadata it is the responsibility of the external CRM integration to deliver that data as needed and to act as the integration point.

Omni-Services & BYO CRM

Other modular components of the NewStore platform leverage the same v2 Customer Profiles APIs that your external CRM integration has covered. As such, by following the instructions above, your external CRM will support any other NewStore service that requires customer metadata to function, such as Clienteling.

Associate App: Custom error messages

By default the Associate App offers a number of error messages providing recommendations on next steps to address issues to associates, depending on the issue. With BYO CRM, you may override these messages by providing your own error message in the API response in accordance with the API specifications.

Merging customer profiles

When Customer Profiles are within the NewStore system we offer a way to merge two profiles together under a number of use cases. However, for BYO CRM, we no longer control the data for the profiles and as such the external CRM must handle merging profiles. This will need to take into account other systems which depend on the customer profile identifier such as order management.