j1.6.1
API Overview
The Shopper Customers API enables you to develop functionality that lets customers log in, and manage their profiles and product lists. Profile management includes ability for shoppers to add or modify addresses and payment methods, and add or modify products to wishlists or favorites. Commerce Cloud provides a rich set of Authentication APIs that include logging in guest shoppers, registered shoppers, agents on behalf of customers and a trusted system authentication on behalf of customers. In all authentication scenarios involving customers, a JSON Web Token (JWT) is generated in Commerce Cloud. Using the JWT, customers can access other Shopper API resources like Orders and Baskets. The application must refresh the JWT every 30 minutes to save the shopper activity (for example, retain products in a shopper's cart) for prolonged periods of time.
Authentication & Authorization
The client requesting the customer information must have access to the Customer and Product List resources. The Shopper Customer API requires a shopper access token from the Shopper Login and API Access Service (SLAS).
You must include the relevant scope(s) in the client ID used to generate the SLAS token. For a full list of permissions, see the Authorization Scopes Catalog.
For details on how to request a shopper access token from SLAS, see the guest user flows for public clients and private clients in the SLAS guides.
Use Cases
Register a New Customer
In this use case, a customer who is browsing on a commerce shopping app built using B2C Commerce APIs would like to create a customer profile, so that they can track their order when logged in on the next visit.
The API flow is shown in the following diagram:
- The shopper opens the shopping app.
- Request an access token from SLAS. For details, see the guest user flows for public clients and private clients in the SLAS guides.
- The SLAS API responds with the shopper access token (JWT).
- The shopper adds a product to their basket.
- Use the Shopper Baskets API to create a basket. The shopper JWT from SLAS is supplied in the authorization header.
- Save the basket with a registered user customer ID (even though the shopper is still a guest). The shopper JWT from SLAS is supplied in the authorization header.
- The shopper creates a profile.
- Use the Shopper Customers API to register the customer.
Authenticate a Trusted System on Behalf of a Customer
In this cross-cloud use case, a Experience Cloud user places an order on Commerce Cloud from the Experience Cloud using the platform APIs. The Experience Cloud app is a trusted system that has a trusted relationship with Commerce Cloud using the OAuth client credentials grant against the Commerce Cloud Account Manager. The Experience Cloud user logs in with a redirect to Salesforce IDM and after successful login, the client application is able to call B2C Commerce APIs on behalf of the customer. Commerce Cloud returns a JWT for the Experience Cloud user and the Experience Cloud user is able to place orders on Commerce Cloud.
The API flow is shown in the following diagram:
Reset Customer Password
In this use case, a shopper who is browsing on a commerce shopping app, built using B2C Commerce APIs, requests to reset their password. The app verifies the shopper's credentials and returns a 404 if verification fails. Otherwise, when the shopper requests their password to be reset, the app first creates a password reset token using the shopper’s login ID, and an account manager token (obtained using the client credentials grant). After the app has the password reset token, the app can prompt the shopper for new password. Any app-level customization, such as sending a password reset email, can be done at this step. Finally, the app calls the reset endpoint to reset the customer’s password.
Update Shopper LoginId
In this use case, in order to update a shopper's loginId, the PATCH /customers/{customerId} call can be used starting B2C Commerce Cloud GA release 24.7. The new field in the request called currentPassword is mandatory and needs to match the shopper's existing password. If this field is not provided or does not match the existing shopper password when trying to update loginId, a HTTP 400 rsponse will be returned. If the loginId field is not sent in the PATCH request body, the currentPassword field is not required.
**Note: After the loginId is updated, a new SLAS token must be fetched for the shopper for subsequent calls.
Use Hooks
For details working with hooks, see Extensibility with Hooks.