CRM Integration Guide

At present only a one-way integration from LOKE to a CRM is supported.

Typically a CRM integrated with LOKE will support the following behaviour:

1. A synchronization of past/existing customer profiles at the time of connection.
2. A real-time synchronization of new/future customer profiles at the time of registration in LOKE.
3. A real-time synchronization of transactional events, such as customer orders and payments.
4. A synchronization of list membership. See "what are LOKE customer lists" below.

What are LOKE Customer Lists

LOKE Customer Lists allow customers to be grouped together. Each LOKE customer can be in many lists.

A customer is typically added to a list either by interecting with a promotion, entering a code, or manually via staff in the admin UI.

A customer is removed from a list manually via staff in the admin UI.

Step-by-Step Guide

Authenticating

Before you can fetch data or subscribe to webhooks you will need an access token. Refer to Authentication for more info on this.

Synchronization of Existing Profiles

Typically when a CRM is first activated or configured for a LOKE organisation there will already be customer profiles in place. In order to function as expected there typically needs to be an initial customer synchronization to get these records into the CRM.

To do this you will typically want to fetch from the Customers Endpoint.

It should be noted that most CRM integrations will likely be intended for use by more than 1 LOKE organization. As such you will typically need to do this for each and every organization configured to use the CRM.

Typically this is a one-off step when first enabling the integration for a customer.

When listing customers via this endpoint don't forget to adhere to paging headers.

NOTE: where possible use the id field on the LOKE customer as a reference in the CRM. A customer's email address and mobile number may change over time, but the ID will always remain the same.

Subscribing to Webhooks

After authenticating an organization we now have access to subcribe to webhooks. Webhooks will be sent to subscribed clients following certain events in the LOKE platform.

See the Create or Update a subscription section for help on doing this.

The events you will probably want to include in the subcription are:

• customer.created so you can add customers as they sign up
• customer.updated so you can update profile changes such as name and contact details
• customer.updated-statistics so you can update points balance and similar statistics on customers
• payment.completed so you can associate spend events with a customer, and also associate what particular items a customer has purchased.
• payment.refunded so you can revert spend events with a customer

NOTE: Because the subscribe webhook is effectively an UPSERT if used with the same reference, it is safe to call multiple times. You could either provide a button to reset or resync the webhook subscription, or simply reset this on every admin login.

Webhooks require an internet facing URL to develop with. Depending on your local environment this can sometimes be challenging. If you haven't had experience developing against webhooks in the past you can try out ngrok to create a HTTPS URL that will be proxied to a local port in your development environment.

It is possible for webhooks to be delayed, so be sure to use the timestamps in the webhook data, not the time of processing as a timestamp (for example the order created date, or the customer created date).

Synchronization of New Profiles

Every time a customer registers there is a customer.created webhook sent.

By subscribing to and using this webhook we can ensure LOKE customers are kept in sync with CRM customers.

NOTE: the customer id field should be used as the unique identifier for a LOKE customer. The email address may change over time.

Keeping Profiles In-sync

LOKE customers can change their profile details such as name and contact information at any time. When they do this a customer.updated webhook is sent.

Use this webhook to update the relevent details in the CRM.

For maximum value it is advisable that you also sync LOKE-specific statistics such as points balance. These statistics are received on the customer.updated-statistics webhook. You can see the available statistics on the CustomerStatistics model.

NOTE: ideally use the customer id to match the CRM customer as email and mobile could be changed in the event. If this is not possible with the CRM the side-effect will be a non-1-to-1 relationship of CRM-to-LOKE customers.

Associating Spend with a Customer

Every time a customer successfully spends in the LOKE platform there is a payment.completed webhook sent.

By subscribing to and using this webhook we can attach spend events and metadata such as names and IDs of items purchased.

You might have noticed there is also a order.completed event. There are many ways for customers to spend in the LOKE platform, and an order is only one of them. When a customer spends by placing an order both a order.completed and a payment.completed event are fired. A payment contains normalized data about the order so that it is consistent with any type of LOKE payment. If you want to capture richer data about an order you may also listen to the order.completed event, but typically this should be unecessary.

Synchronization of Customer Lists

NOTE: at present there are no webhooks for list membership changes.

You can fetch all available lists by using the list all customer lists endpoint. An organization may have many lists, so you probably don't want to synchronize all of them, and will likely want an opt-in type configuration.

Once you have identified which lists need to be synchronized you need to use the show all members endpoint to identify available members, where you can synchronize to the CRM in whatever way is suitable.

At present there is no way to identify changes to a list, so a full resync must be done.