Clienteling SPI for CRM
Implementing the Clienteling SPI allows merchants to use their own system as the system of record for managing customer profiles–configuring Retail Cloud POS to create, update, search, and retrieve customer profiles from the merchant system. This approach provides an alternative to using one of our standard connectors to a CRM (for example, Salesforce Service Cloud or Netsuite).
The Clienteling SPI has three prerequisites:
- Merchant builds the SPI service for the endpoints (i.e., for each clienteling operation to be supported)
- Merchant configures the connector in CMS, specifying the details of the integration between Retail Cloud and the SPI endpoint you’ve built
- Merchant configures the layouts in CMS. Layouts allow you to define a custom form for the POS that will take associate inputs and pass them as parameters in requests to the SPI endpoint
The Clienteling SPI supports four endpoints. See Clienteling SPI for detailed specifications for each endpoint.
| Endpoint Name | Sample Endpoint | Method | Description |
|---|---|---|---|
| CREATE_CUSTOMER | /endpoint/sa/customers | POST | Create new customer profile based on customer data entered in POS. |
| UPDATE_CUSTOMER | /endpoint/sa/customers | PUT | Update existing customer by specifying values for the parameters passed. Customer parameters not provided in the request will be left unchanged. The specific customer to update is identified by customer ID. |
| SEARCH_CUSTOMERS | /endpoint/sa/customers | GET | Search and retrieve customers previously created based on input parameters passed from POS. |
| GET_CUSTOMER | /endpoint/sa/customers/{customerId} | GET | Retrieve customer data based on provided customer ID. |
Merchants can define which customer attributes are passed from the POS to the Clienteling SPI, specifying only the data they wish to track and maintain. For each clienteling operation, the data the associate collects are determined by the fields configured on the corresponding layout.
To better understand the Clienteling SPI, let's consider each endpoint, the specific associate journey that invokes it, the layout used to capture the customer information, and the presentation of data from the SPI response in the POS app.
When a store associate searches for a customer, whether to add them to the cart during checkout or to view their profile during clienteling activities, the associate’s inputs in the Customer Search layout are passed to the SEARCH_CUSTOMERS endpoint.
See the below example of a Customer Search layout, presented as a full-page form when the associate taps the clienteling CTA (the "person" icon) in the top right corner of the home screen. Results retrieved from the SEARCH_CUSTOMERS endpoint's response are presented in a list view below the search form.
Selecting one of the profiles in the list will login that customer. When a customer is logged in, the customer's first name and profile photo are shown in the top right corner of the home screen.
When a store associate creates a new customer profile, the fields in the Customer Signup layout are passed in a request to the CREATE_CUSTOMER endpoint. See the below example of a Customer Signup layout. Associates typically will access this layout when searching for a customer and finding no results or during checkout if they have not already logged a customer in for the cart.
After logging in a customer, the associate can view the customer’s profile, and, as needed, make edits to the profile, which result in calls to the GET_CUSTOMER and UPDATE_CUSTOMER endpoints, respectively. The View profile CTA in the below screenshot will take the associate to the customer's profile.
Below is an example of a Customer 360 layout, the customer's profile rendered with the details from the GET_CUSTOMER response. For more detail on setting up this layout, see: Understanding & Configuring Customer 360°.
An associate might update a customer's profile when acquiring new or updated information about a customer's preferences, location, contact details, and personal attributes. The Update Customer layout is typically a form with the same fields as the Customer Signup layout, pre-filled with the existing values against each customer profile attribute. The form is accessed via a deep link configured on the customer's profile. Upon making and submitting the desired edits, the associate will trigger a request to the UPDATE_CUSTOMER endpoint, and result in the specified changes to the customer's profile.
To summarize, the clienteling endpoints are invoked in the following POS flows:
| Endpoint Name | Associate Journey on POS | Layout |
|---|---|---|
| SEARCH_CUSTOMERS | Associate performs a customer search to find an existing profile: - Whether customer already logged in and changing to another profile, or none logged in - Whether during checkout or clienteling activities | Customer Search |
| CREATE_CUSTOMER | Create customer profile using New Customer Sign-up | Customer Signup |
| GET_CUSTOMER | Selecting a customer’s profile from the customer search results | Retrieving a customer’s details does not require a layout, but it’s important to have a clienteling profile layout so associates can view key attributes, order history, and loyalty status of a customer. |
| UPDATE_CUSTOMER | Edit customer profile, e.g., with Edit layout accessed from Customer 360 | Customer Signup |
When creating layouts for the above Clienteling operations, refer to Clienteling SPI Field Mapping for a complete mapping between the template tags you configure on the layout and the corresponding attributes of the objects exchanged with the SPI endpoint.
In general, the core resource being exchanged in Clienteling workflows is the customer object, which comprises addresses, consents, customer profiles, and loyalty profiles.
This object represents a shopper–their name and contact information, their addresses for billing and shipping, and many other attributes, including, whether they’ve consented to terms and conditions, marketing communications, and loyalty program enrollment.
For each parameter of the customer object, see the below for a summary overview:
| Parameter | Type | Description |
|---|---|---|
| addressList | Array of dictionaries | Customer's list of Addresses used for billing and shipping. The Address object represents a customer address, typically for shipping, but also for billing, when applicable. It is passed as part of the Clienteling SPI endpoints’ addressList parameter, which is all shipping and billing addresses associated to a customer. It is also part of the Customer object, in profile.address and customerLoyaltyProfile.address. |
| consents | Dictionary of booleans | Customer consents. Child attributes: • consents.agreeToTC • consents.directMailSignUp • consents.eReceipt • consents.loyaltySignUp • consents.newsLetterSignUp • consents.phoneSignUp • consents.smsSignUp |
| profile | Dictionary | Customer profile object. Some of its child attributes are: • address • customerId • firstName • postalCode • customerGroup • loyaltyId • preferredLanguage • country • allowSmsNotifications It encapsulates a customer’s personal and contact information, their loyalty ID, and other attributes. For order-related SPIs and webhooks, the profile object is used to exchange customer information associated with a sale. |
| customerLoyaltyProfile | Dictionary | This object represents the Customer’s loyalty profile, which is used if you are managing a customer loyalty program in Retail Cloud. Some of its child attributes are: • accountNumber • address • cashRewards • currentPoints • currentStoreCredit • currentTier • customLoyaltyAttributes • firstName • lastName |
| storeAttribution | Dictionary | This captures the store ID and ID of the associate who creates the customer account and completes the transaction. |
In this scenario, a store associate completes and submits the Customer Signup layout for the shopper, triggering a POST request to the merchant’s CREATE_CUSTOMER SPI endpoint. A response with the new customer object is provided to the POS.
Request
Response
Note that the customer's identifying attributes (name, email, etc.) and address are added to the customer profile object under customer.profile and customer.profile.address, respectively. The customer's address is also added to customer.loyaltyProfile.address (because the customer consented to participating in the merchant's loyalty program) and to customer.addressList.
In this scenario, a store associate is placing an order for a customer. The associate searches and retrieves the customer’s profile, logging them in on the POS. Then, when selecting a shipping address for the order, the associate enters a new address for the customer instead of the existing address on file. The option to “Save this address to profile” is toggled on. After adding the new shipping address, a PUT request is sent to the merchant’s UPDATE_CUSTOMER SPI endpoint. As a result, the new address is added to the addressList array in the Customer object, customer.addressList.
Request
Response
In this scenario, a store associate searches and retrieves an existing customer, logging them in on the POS. Then the associate uses a deep link on that customer’s clienteling profile to edit the profile information. The associate edits the customer’s profile address. When the edits on the customer layout are submitted, a PUT request is sent to the merchant’s UPDATE_CUSTOMER SPI endpoint.
Below you can see the request and response payloads for that operation. Notice that, in the response, there are three changes:
- customer.loyaltyProfile.address and customer.profile.address are updated to the new address
- and the new address is appended to the customer.addressList array
Request
Response