--- schema_version: "1" id: 3204e11f0797defb8472c5d390eb7648f1b2f053968c362cf7c6285a1b475135 title: Clienteling SPI collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/commerce-cloud/retail-cloud/reference/generated-api-specs/clienteling-spi.md canonical_url: https://developer.salesforce.com/docs/commerce/retail-cloud/references/clienteling-spi source_site: developer.salesforce.com content_type: documentation content_hash: eaedb621528696de4b9fd9a87e92f9e2cceb9156f5643c78baf4ac04ae1ddd48 products: - Point of Sale for Developers - Salesforce APIs --- Clienteling SPI # Clienteling SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/clienteling-spi/clienteling-spi-oas-public.yaml) Merchant SPI to create, search, and retrieve customers from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in Point of Sale (POS) CMS for the POS to use during clienteling operations. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) **Version:** 2.3.4 ## Tags ### Clienteling SPI [Download specification](https://developer.salesforce.com/static/commercecloud/retail-cloud/clienteling-spi/clienteling-spi-oas-public.yaml) Merchant SPI to create, search, and retrieve customers from the merchant's system. These are sample endpoints that provide specifications for merchants on how to implement APIs on their end and then configure them in Point of Sale (POS) CMS for the POS to use during clienteling operations. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) ## Operations ### GET Search and retrieve customers. `GET /merchant/spi/sample/endpoint/sa/customers` Operation ID: `searchCustomers`. Tags: Clienteling SPI. Search and retrieve customers based on input parameters. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) #### Parameters * `start` (query, integer (int32)) Default: `0`. * `count` (query, integer (int32)) Default: `20`. * `firstName` (query, string) * `lastName` (query, string) * `phone` (query, string) * `email` (query, string) * `id` (query, string) * `postalCode` (query, string) * `searchString` (query, string) * `countryCode` (query, string) #### Responses * **default** Default response. Media type: `application/json`. Schema: `SearchCustomersResponse`. ### PUT Update customer. `PUT /merchant/spi/sample/endpoint/sa/customers` Operation ID: `updateCustomer`. Tags: Clienteling SPI. Update the existing customer. The existing customerId is provided under 'profile.customerId'. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) #### Request body Media type: `application/json`. Schema: `UpdateCustomerRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `UpdateCustomerResponse`. ### POST Create customer. `POST /merchant/spi/sample/endpoint/sa/customers` Operation ID: `createCustomer`. Tags: Clienteling SPI. Create customer based on customer data entered in POS. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) #### Request body Media type: `application/json`. Schema: `CreateCustomerRequest`. #### Responses * **default** Default response. Media type: `application/json`. Schema: `CreateCustomerResponse`. ### GET Retrieve customer details. `GET /merchant/spi/sample/endpoint/sa/customers/{customerId}` Operation ID: `getCustomer`. Tags: Clienteling SPI. Retrieve customer data based on customer ID. Merchant must implement this endpoint per this specification and then configure it in CMS. For more information, see [Point of Sale API, SPI, and Webhook Overview](https://developer.salesforce.com/docs/commerce/retail-cloud/guide/retail-cloud-api-spi-webhook-specs.html) #### Parameters * `customerId` (path, string, required) #### Responses * **default** Default response. Media type: `application/json`. Schema: `GetCustomerResponse`. ## Schemas ### SearchCustomersResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `customers` (_array of CustomerData_, nullable) List of Customers. * `associateSessionId` (_string_, nullable) Store associate session ID. * `error` (_boolean_) ### UpdateCustomerRequest * `profile` (_Profile_, required) * `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only. * `consents` (_Consents_) * `storeAttribution` (_SpiStoreAttribution_) * `loyaltyProfile` (_CustomerLoyaltyProfile_) ### UpdateCustomerResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `profile` (_Profile_, required) * `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address. * `loyaltyProfile` (_CustomerLoyaltyProfile_) * `consents` (_Consents_) * `error` (_boolean_) ### CreateCustomerRequest * `profile` (_Profile_, required) * `addressList` (_array of Address_, nullable, deprecated) Deprecated. Not supported in create or update customer requests. Use profile.address instead. To add additional addresses, use the Customer Address SPI (CREATE\_CUSTOMER\_ADDRESS or UPDATE\_CUSTOMER\_ADDRESS). The complete address collection is returned in responses only. * `consents` (_Consents_) * `storeAttribution` (_SpiStoreAttribution_) ### CreateCustomerResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `profile` (_Profile_, required) * `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system, contains the complete address collection, including the primary address from profile.address. * `loyaltyProfile` (_CustomerLoyaltyProfile_) * `consents` (_Consents_) * `error` (_boolean_) ### GetCustomerResponse * `errorMessage` (_string_, nullable) Error message shown to the user. Example: `Invalid request. Please check the request and try again.`. * `errorCode` (_string_, nullable) Error code shown to the user. Example: `INTERNAL_ERROR`. * `sessionId` (_string_) Active session ID. * `profile` (_Profile_, required) * `addressList` (_array of Address_, nullable) List of all customer addresses. In responses returned to POS from the merchant system: contains the complete address collection, including the primary address from profile.address. * `cartProductList` (_array of ClientelingCartProduct_, nullable) List of products saved in customer cart. * `loyaltyProfile` (_CustomerLoyaltyProfile_) * `consents` (_Consents_) * `error` (_boolean_) ### CustomerData List of Customers. * `profile` (_Profile_, required) * `addressList` (_array of Address_) Customer's addresses. * `cartProductList` (_array of ClientelingCartProduct_) Wish list or products from customer's abandoned cart. * `loyaltyProfile` (_CustomerLoyaltyProfile_) * `consents` (_Consents_) ### Profile Customer profile. In case of sale and return transactions, it is mandatory if a signed-in customer places an order or a return. Note: If an order is imported from an external system into POS, only customerId and alternateCustomerId from the profile object are used. * `customerId` (_string_, nullable) Customer ID. Optional for guest customer. Mandatory for logged-in customer. * `alternateCustomerId` (_string_, nullable) Alternate Customer ID. * `email` (_string_, nullable) Customer Email ID. Optional for guest customer. Mandatory for logged-in customer. * `salutation` (_string_, nullable) Salutation. * `firstName` (_string_, nullable) Customer first name Optional for guest customer. Mandatory for logged-in customer. * `secondName` (_string_, nullable) Customer second name. * `lastName` (_string_, nullable) Customer last name Optional for guest customer. Mandatory for logged-in customer. * `suffix` (_string_, nullable) Suffix. * `address` (_object_) Customer address. In requests sent from POS to the merchant system: accepts any customer address (primary, secondary, or other). In responses returned to POS from the merchant system: contains the customer's primary address. Includes all fields of `Address`. * `phoneHome` (_string_, nullable) Phone Home. * `phoneMobile` (_string_, nullable) Phone Mobile. This is the primary phone number for the customer. * `phoneBusiness` (_string_, nullable) Phone Business. * `fax` (_string_, nullable) Fax. * `birthmonth` (_string_, nullable) Customer birth month. Not applicable for order related scenarios like export/import. * `wallets` (_array of Wallet_, nullable) Customer wallets containing tokenized cards for Card on File payments. Optional field returned only when customer has stored cards. * `eReceipt` (_boolean_, nullable) Customer eReceipt indicator. Not applicable for order related scenarios like export/import. * `country` (_string_, nullable) Country. * `customerGroup` (_string_, nullable) Customer group. Not applicable for order related scenarios like export/import. * `preferredLanguage` (_string_, nullable) Preferred language. Not applicable for order related scenarios like export/import. * `allowSmsNotifications` (_boolean_, nullable) SMS sign up checkbox. Not applicable for order related scenarios like export/import. * `loyaltyId` (_string_, nullable) Loyalty Id of the customer. * `logoUrl` (_string_, nullable) The URL for the logo to be displayed for loyalty customers. Not applicable for order related scenarios like export/import. ### Address Address **Billing Address:** It contains first and last name of billing person. It is applicable if order is associated with signed-in customer or if an order requires billing address. Note: If item level shipping method or item level shipping address is enabled, use the shippingAddress from deliveryGroups. For more details, see:. * `salutation` (_string_, nullable) Salutation. * `firstName` (_string_) Customer first name saved for address. Maximum length: 64. * `secondName` (_string_, nullable) Customer second name saved for address. Maximum length: 64. * `lastName` (_string_, nullable) Customer last name saved for address. Maximum length: 64. * `suffix` (_string_, nullable) Suffix. * `addressLine1` (_string_, required) Address Line 1. Maximum length: 256. * `addressLine2` (_string_, nullable) Address Line 2. Maximum length: 256. * `city` (_string_, required) City. Maximum length: 64. * `state` (_string_, required) State. Maximum length: 32. * `postalCode` (_string_, required) Postal Code. Maximum length: 16. * `countryCode` (_string_, nullable) Country Code. Maximum length: 32. * `phone` (_string_, nullable) Phone. Maximum length: 24. * `storeId` (_string_, nullable) Store ID if it is store address. * `emailAddress` (_string_, nullable) Customer Email Address. * `country` (_string_, nullable) Country. * `defaultBilling` (_boolean_) * `defaultShipping` (_boolean_) ### Consents Consents for different types of sign ups. * `smsSignUp` (_boolean_, nullable) Consent for SMS signup. * `newsLetterSignUp` (_boolean_, nullable) Consent for news letter signup. * `agreeToTC` (_boolean_, nullable) Consent for terms and conditions. * `directMailSignUp` (_boolean_, nullable) Consent for direct mail signup. * `phoneSignUp` (_boolean_, nullable) Consent for phone signup. * `loyaltySignUp` (_boolean_, nullable) Consent for loyalty signup. * `eReceipt` (_boolean_, nullable) Consent for eReceipt signup. ### SpiStoreAttribution Store ID and associate details of created customer. * `storeAssociateId` (_string_, nullable) ID of the store associate who creates customer account and rings the transaction. * `storeId` (_string_, nullable) Store Id. ### CustomerLoyaltyProfile The loyalty profile of the customer if they are enrolled in Loyalty program. * `loyaltyId` (_string_) Loyalty Id of the customer. * `firstName` (_string_) Customer's first name. * `lastName` (_string_) Customer's last name. * `accountNumber` (_string_) Customer's loyalty account number. * `loyaltyStatusCode` (_string_, nullable) Customer's loyalty status code. * `currentPoints` (_integer (int32)_, nullable) Customer's current loyalty points. If provided, it will be used for validation against the individual reward points (If points are sent in reward). * `currentStoreCredit` (_number (double)_, nullable) Customer's current store credit. * `lifetimePoints` (_integer (int32)_, nullable) Loyalty point accumulated so far by the customer. * `nextRewardPoints` (_integer (int32)_, nullable) Loyalty point eligible for next reward cycle. * `transactions` (_Transactions_) * `rewards` (_array of Reward_, nullable) Earned rewards. * `tierLevelLabel` (_string_, nullable) Customer's tier level label. * `tierLevelValue` (_string_, nullable) Customer's tier level value. * `tierLevelCode` (_string_, nullable) Customer's tier level code. * `redemptionType` (_string_) * `internalMemberId` (_string_, nullable) Customer's internal member ID. * `homePhoneNumber` (_string_, nullable) Customer's home phone number. * `mobilePhoneNumber` (_string_, nullable) Customer's mobile phone number. * `address` (_Address_) * `currentTier` (_Tier_) * `nextTier` (_Tier_) * `customLoyaltyAttributes` (_CustomAttributes_) * `totalRewardsAmount` (_number_, nullable) Total amount value of all the rewards available for the customer. If provided, this will be used for validation when applying the individual rewards. * `loyaltyIdBarCodeType` (_string_) ### ClientelingCartProduct Summary of a product line in the customer's saved cart. Current implementation only supports productId as the details are fetched from the product catalog. * `productId` (_string_, required) Product / SKU identifier of the product. ### Wallet Tokenized card stored in customer wallet for Card on File payments. * `firstName` (_string_) Cardholder's first name as shown on the payment card, used for ID verification. * `secondName` (_string_, nullable) Cardholder's middle name or additional given name, if present. * `lastName` (_string_) Cardholder's last name as shown on the payment card, used for ID verification. * `program` (_string_, required) Program identifier, for example, 'CB' for Crate & Barrel. Example: `CB`. * `shopperReference` (_string_, required) Payment method ID from payment gateway (shopper reference). Example: `336df316-56b3-430c-a366-ea5e8d694582`. * `storedPaymentMethodId` (_string_, required) Card identifier from card issuer (stored payment method ID). Example: `xyz12345677777`. * `cardAlias` (_string_, required) Identifier of the stored card. Example: `xyz12345677777`. * `status` (_string_, required) Status of the wallet card. Allowed values: `Active`, `Inactive`. Example: `Active`. * `type` (_string_, required) Type of the wallet card. Allowed values: `Virtual`, `Physical`. Example: `Virtual`. * `cardType` (_string_, required) Card network, for example, Visa, Mastercard, or Amex. Example: `Visa`. * `cardLastFour` (_string_, required) Last 4 digits of the card number. Example: `1111`. ### Transactions Loyalty transactions. * `nextStartMonth` (_integer (int32)_) * `txnActivity` (_array of TransactionActivity_) ### Reward Earned rewards. * `issueDate` (_integer (int64)_) * `expiryDate` (_integer (int64)_) * `description` (_string_) * `amount` (_number_) Amount value of the reward. Required for reward types : Discount and Tender. * `rewardName` (_string_) * `code` (_string_) * `pin` (_string_) * `codeType` (_string_) * `labelText` (_string_) * `disclaimerText` (_string_) * `rewardType` (_string_) Allowed values: `Discount`, `Coupon`, `Tender`. * `isImageOnly` (_boolean_) * `rewardImageURL` (_string_) * `rewardInputType` (_string_) * `status` (_string_) Allowed values: `REDEEMED`, `EXPIRED`, `AVAILABLE`, `CANCELLED`. * `statusDesc` (_string_) * `canRedeemNow` (_boolean_) * `redeemedDate` (_integer (int64)_) * `customAttributes` (_object_) Additional properties: `object`. * `rewardId` (_string_, required, read-only) The ID of the loyalty reward. In the case of reward coupon, it will be coupon code. In the case of discount reward, it is unique identifier. Maximum length: 512. * `combinable` (_boolean_) Specifies whether multiple rewards can be applied to the same cart. * `points` (_integer (int32)_, nullable) Optional points value for the reward, if sent, it will be used for display and for validation against the current points of the customer ( loyaltyProfile.currentPoints). ### Tier Customer's next tier details. * `name` (_string_) Tier name. * `minPoints` (_number_) Minimum points required for the tier. * `display` (_string_) * `points` (_integer (int32)_) * `memberSince` (_integer (int64)_) Member since, of this tier. * `title` (_string_) * `subTitle` (_string_) * `imageUrl` (_string_) * `expiryDate` (_integer (int64)_) Expiry date of the customer's membership. ### CustomAttributes Custom attributes. * `customLabel` (_string_) * `customValues` (_array of CustomValue_) ### TransactionActivity * `orderId` (_string_) * `date` (_integer (int64)_) * `description` (_string_) * `points` (_integer (int32)_) * `amount` (_number_) * `pointStatus` (_string_) Allowed values: `EARNED`, `PENDING`, `REWARD`, `REDEEMED`. * `customAttributes` (_object_) Additional properties: `object`. ### CustomValue * `laabel` (_string_) * `value` (_string_) * `iconType` (_string_)