Create a shopper profile

To create a new shopper profile, issue a POST request to the /ccadmin/v1/profiles endpoint on the administration server.

Specify the values of the profile properties as a JSON map in the body of the request. For example:

POST /ccadmin/v1/profiles  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
    "receiveEmail": "yes",
    "lastName": "Wilson",
    "locale": "en_US",
    "email": "fredW@example.com",
    "firstName": "Fred"
}

If the profile is created successfully, the response body returned includes the ID for the new profile and a link to the URL used in the request:

{
    "id": "120000",
    "links": [
        {
            "rel": "self",
            "href": "http://myserver.example.com:7002/ccadmin/v1/profiles"
        }
    ]
}

Specify the email address and login

The value of the login property on the profile is used as the shopper’s username. Each username must be unique. On many storefronts, the username is also the shopper’s email address, in which case the value of the login property is the same as the value of the email property.

When you create a profile through an API call, the request must explicitly set the email property, but can omit the login property. If the request does not specify a value for the login property, it is set to the same value as the email property. For example, the following request creates a profile with bobW@example.com as both the username and the email address:

POST /ccadmin/v1/profiles HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
    "receiveEmail": "yes",
    "lastName": "Wilson",
    "email": "bobW@example.com",
    "firstName": "Bob"
}

If you want the username to be different from the email address, you can set separate values for the email and login properties in the request. For example, the following request creates a profile with fwilson as the username and fredW@example.com as the email address:

POST /ccadmin/v1/profiles HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
    "login": "fwilson",
    "receiveEmail": "yes",
    "lastName": "Wilson",
    "email": "fredW@example.com",
    "firstName": "Fred"
}

Allow profiles to share an email address

One reason you may want the login and email values to differ is to allow multiple profiles to share an email address. By default, Commerce requires each profile to have a unique email address, but your business needs may make this restriction undesirable. If so, you can use the following call to allow multiple profiles to share the same email address:

PUT /ccadmin/v1/merchant/shopperProfileConfiguration  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "duplicateEmailsAllowed": true
}

Note that once your Commerce instance has profiles that share an email address, you cannot set duplicateEmailsAllowed back to false. If you try to do this, the call will return an error.

Block weak passwords

As discussed in the Configure Shopper Settings, you can configure password policies through the Commerce administration interface. The purpose of these settings is to ensure that shoppers do not use passwords that are easy to guess.

The properties set through the administration interface can also be set using the savePolicies endpoint in the Admin API. In addition to these properties, this endpoint can set the blockCommonPasswords property, which has no equivalent setting in the administration interface. If blockCommonPasswords is set to true, Commerce rejects weak passwords, regardless of whether they meet the criteria specified in the other properties.

The properties set using this endpoint are site-specific, so the call must specify the site using the x-ccsite header. For example, the following call specifies values for a site's password policy settings, including blockCommonPasswords, which it sets to true:

PUT /ccadmin/v1/merchant/profilePolicies  HTTP/1.1
Authorization: Bearer <access_token>
x-ccsite: 100002

{
  "guestCheckoutEnabled": true,
  "numberOfPreviousPasswords": 3,
  "numberOfPreviousPasswordsMinVal": 1,
  "passwordExpirationEnabled": false,
  "passwordExpirationLengthMinVal": 1,
  "sessionTimeoutLength": 15,
  "cannotUsePreviousPasswords": false,
  "passwordExpirationLength": 90,
  "minPasswordLengthMinVal": 4,
  "sessionTimeoutEnabled": true,
  "minPasswordLengthMaxVal": 64,
  "useNumber": true,
  "cannotUseUsername": false,
  "useMinPasswordLength": true,
  "minPasswordLength": 8,
  "numberOfPreviousPasswordsMaxVal": 6,
  "useMixedCase": false,
  "sessionTimeoutLengthMinVal": 1,
  "sessionTimeoutLengthMaxVal": 120,
  "useSymbol": false,
  "blockCommonPasswords": true
}

If blockCommonPasswords is true, Commerce rejects any password that appears in its dictionary of weak passwords. When the shopper specifies a new password, it is compared against all of the entries in the dictionary, and if it matches one of those entries, it is rejected.

In addition to the passwords listed in the dictionary, you can specify your own list of passwords to block using the updateRestrictedWords endpoint. For example:

POST /ccadmin/v1/merchant/profilePolicies/updateRestrictedWords  HTTP/1.1
Authorization: Bearer <access_token>

{
     "add": ["frog", "cow", "pig"]
}

The response includes an items array that lists your blocked entries:

{
  "links": [
    {
      "rel": "self",
      "href": "http://myserver.example.com:7002/ccadmin/v1/merchant/profilePolicies/updateRestrictedWords"
    }
  ],
  "items": [
    "frog",
    "cow",
    "pig"
  ]
}

You can also display your current list using the getRestrictedWords endpoint (GET /ccadmin/v1/merchant/profilePolicies/restrictedWords).

Note that your list of blocked passwords is not site-specific. The entries you specify apply to all sites whose blockCommonPasswords property is true.

The updateRestrictedWords endpoint can also take a delete array for specifying entries to remove from your list. For example:

POST /ccadmin/v1/merchant/profilePolicies/updateRestrictedWords  HTTP/1.1
Authorization: Bearer <access_token>

{
     "delete": ["frog", "cow"]
}

Deleting entries affects only your own list of blocked passwords. You cannot modify the dictionary that Commerce uses. For example, if you add an entry to your list that matches a value already in the dictionary, and subsequently delete that entry from your list, it does not affect the entry for that value in the dictionary.

Note that changing settings in the password policy does not invalidate existing passwords. The policy change is applied only when a shopper attempts to set a new password.

Disable soft login

As discussed in Configure Shopper Settings, a logged-out shopper can still see personalized content based on their profile. This is referred to as soft login. Soft login is enabled by default. You can use the /ccadmin/v1/merchant/profilePolicies REST API endpoint to disable or enable it.

If softLoginEnabled is set to false, Commerce disables soft login. The following call sets softLoginEnabled to false for the specified site:

PUT /ccadmin/v1/merchant/profilePolicies  HTTP/1.1
Authorization: Bearer <access_token>
x-ccsite: 100002

{
  "softLoginEnabled": false
}

Create a shopper profile on an instance running multiple sites

If you are running multiple sites on your Commerce instance, shopper profiles are shared by all of these sites. If a shopper registers on one site running on the instance, the shopper’s profile is automatically available on all sites running on the instance.

However, the values of certain properties in the profile can be site-specific. For example, the values of the receiveEmail property are site-specific.

When you create a shopper profile using a POST request, you can specify a site using the x-ccsite header, as described in Use the APIs on instances running multiple sites. The resulting profile applies to all of the sites on your Commerce instance, but the value you provide for a site-specific property applies only to the site you specify. (If you do not specify a site, the value is applied to the default site only.) On all other sites, the value of this property is set to its default. You can modify the property on a specific site using a PUT request. For example:

PUT /ccadmin/v1/profiles/120000  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>
x-ccsite: 100001

{
    "receiveEmail": "yes"
}

Similarly, if you use a GET request to view a profile, the value returned for a site-specific property reflects the site specified in the x-ccsite header, or the default site if no site is specified.

Set a site-specific profile property for multiple sites

If your Commerce instance is running multiple sites, shoppers can set site-specific profile properties for each site individually. For example, the storefront for each site can provide a checkbox for setting the receiveEmail property, with the setting applying only to the current site.

A drawback of this approach is that in order to configure settings on all sites, a shopper must access each site separately. To simplify profile configuration, you may instead want to provide a way for the shopper to configure multiple sites in one place.

To enable this, you can modify your storefront to use the updateSiteProperties endpoint in the Store API. This endpoint sets the values of site-specific properties of the current profile (the profile in the current calling context). Note that the current profile must be for a registered shopper, which means the shopper must be logged in.

For example, the following call sets the value of the receiveEmail property of the current profile for two different sites:

PUT /ccstore/v1/profiles/current/siteProperties  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

{
  "siteProperties": [
    {
      "site": {
        "id": "siteUS"
      },
      "properties": {
        "receiveEmail": "yes"
      }
    },
    {
      "site": {
        "id": "siteUK"
      },
      "properties": {
        "receiveEmail": "no"
      }
    }
  ]
}

The response shows the values of the receiveEmail property for all sites on which it has been set. For example, the following is a portion of the response to the above request:

{
  ...
    "items": [
        {
            "site": {
                "id": "siteUK"
            },
            "properties": {
                "receiveEmail": "no"
            }
        },
        {
            "site": {
                "id": "siteUS"
            },
            "properties": {
                "receiveEmail": "yes"
            }
        }
    ],
    "totalNumberOfItems": 2
}

You can also display the current values of site-specific properties using the listSiteProperties endpoint. For example:

GET /ccstore/v1/profiles/current/siteProperties  HTTP/1.1
Content-Type: application/json
Authorization: Bearer <access_token>

The response contains the same data as the updateSiteProperties endpoint response.

Some things to note about using the updateSiteProperties and listSiteProperties endpoints:

Before you can set the value of a site-specific property for an individual site, the site object’s enabled property must be set to true, and the site object must be published.
You can use the updateSiteProperties endpoint to update the value of a site-specific property for all of the sites running on the instance, or for a subset of the sites. In the latter case, you include only the sites you want to update in the body of the request.
Setting the values of a site-specific property affects only sites that have already been created. If you subsequently create an additional site, the property's value for that site is set to the property's default value on all shopper profiles.
If the value of a site-specific property has not been set explicitly for a site, the value for that site is set to the property's default value, but no entry for the site is included in the updateSiteProperties or listSiteProperties response.

Send site-specific properties in webhooks

Several webhooks include profile data for the current shopper in their request bodies. This data includes a sitePropertiesList array that lists the values of site-specific properties such as receiveEmail for each site. These webhooks are:

Cart Idle
Shopper Registration
Shopper Account Update
External Price Validation
External Tax Calculation

The following is an example of a sitePropertiesList array that lists site-specific property values in a webhook request:

"sitePropertiesList": [
      {
         "site": {"id": "siteDE"},
         "properties": {"receiveEmail": "no"}
      },
      {
         "site": {"id": "siteUS"},
         "properties": {"receiveEmail": "yes"}
      }
   ]