Content Comparison

Default customer form

Default fields

By default, when the catalogue is activated, a standard form is proposed with the following fields:

Default field

Type

Mandatory

Default Validation

Last Name

text

Yes

No

First Name

text

Yes

No

Email

email

Yes

Yes

Phone Number

tel

Yes

Yes

Country

list

Yes

Yes

Address 1

text

Yes

No

Address 2

text

No

No

City

text

Yes

No

Postal code

text

Yes

No

This is what the default customer form looks like:

Image Removed

Specific configurations on the default form

Once the basket has been validated, you will be taken to the customer information section. At this stage, you can search for a customer already known to CRM (Customer Relationship Manager), or create a new one.

Image Added

External CRM connection

The CRM is used to manage the creation, the edition and the retrieval of customer information.

If no configuration is made, the Store App will automatically connect to our internal CRM. The database will be empty at first, but will fill up as customers are created from the Order In Store. However, we strongly recommend connecting to the external customer CRM.

To connect to the external CRM, you need to set a specific configuration in the Configuration > Store App > Extensions > CRM section of the backoffice. Please indicate "external": true and the API route link in the key "url".

Expand
title Example
Path: Configuration > Store App > Extensions > CRM Image Added

Retrieve a customer

Whether you're connected to the external or internal CRM, a search bar allows you to search for customers in the database. The search is performed by sending a "pattern" field to the API corresponding to the text written.

By default, this request is sent for each character from the 3rd onwards. The results returned by the API are displayed as a list below the search bar. Last name, first name, email and phone number are displayed.

Image Added

It is also possible to display a “Search” button and launch the query only when this button is clicked. To do this, activate the key "use_search_button": true

{
    "use_search_button": true
}

Image Added

If the external CRM needs additional information from the user or store, you can add fields to the request body with the customer.search_request_params.external_parameters configuration key. Added fields must be valid paths in the endpoint or user structure, surrounded by % characters. See example below.

{
    "customer": {
        "

search_request_

params": 

{
           

Image Removed

• Change the list of countries:

The default form proposes the following countries: France, Belgium, Germany, Italy, Luxembourg, Spain, Switzerland, United Kingdom. An override can be made per sales channel using the configuration "countries.{sales_channel}.{list of countries}" in the Configuration > Store App > Pages > Catalog > Specific settings page in the Options section.

Country codes must be in ISO-3166 format. Logos and translations will add themselves in the Store App.

 "external_parameters": {
                "country_code": "%endpoint.address.regions.country.code%",
                "brand": "%endpoint.classification.brand%",
                "

user": 

"%user.id%"
            

}
        }
   

Image Removed

Add custom fields

}
}

Customer creation

General parameters

Customer information is always mandatory when placing an order. However, it is possible to authorize an order by giving only the e-mail address when making an immediate purchase. To do this, activate the quick_purchase configuration key. This option is not available for Click & Collect or Home Delivery orders.

If the fields added are to be applied to all the project's sales channels, then the field "_ALL_" must be given in the {sales_channel} part.

Here is a configuration applied to all the sales channels with ... being the structure of the custom fields that we will see below.

{
    "

quick_purchase": 

true
}

Image Added

By default, the basic customer form is displayed below the search so that a new customer can be created. However, you can disable the creation of new customers and make the customer form disappear by deactivating the configuration “create_customer”.

{
    

Custom fields structure

Inside the {sales_channel} entity ( or "_ALL_") there is an array of objects. Each object corresponds to a custom field to be added to the form. Here is the configuration to be entered for each custom field.

Field

Type

Mandatory

Description

name

string

Yes

This key is used to give the identifier of the field.

This id must match with parameters used in POST /customers request or PATCH /customers/<id>

target

string

No

Indicates whether the field should be saved in the customer structure or the address structure. By default, customer is applied.

Only used for information.{custom_field} and external_id names, the others are automatically redirected to the right structure.

type

string

No

Type of the field. By default, the text type is used.

required

boolean

No

Indicates whether the field is mandatory or not. By default, custom fields are optional.

position_after

string

No

This key defines the name of the form element to which it must be placed after. Please note, the form element must be in the default form or declared before in the same form.

It it also possible to place the element on the top of the form with the value :first. If multiple elements are placed in first position, they will be placed in the order in which they are configured.

If not defined, the element form will be placed at the bottom of the form.

validation

object

No

Enables to add custom validation to the field, which will be checked when the create button is clicked.

Expand
title Examples
Require a 5-digit postcode Code Block language json "validation": { "min_characters": 5, "max_characters": 5 } Use a custom validation for UK postcode and add a custom message if the field is invalid Code Block language json "validation": { "regex": "^([a-zA-Z]){1}([0-9][0-9]|[0-9]|[a-zA-Z][0-9][a-zA-Z]|[a-zAZ][0-9][0-9]|[a-zAZ][0-9]|[0-9][a-zAZ]){1}([ ])*([0-9][a-zA-z][a-zA-z]){1}$", "error_translation_key": "UK_postcode_error_message" } And then translate the key form.validation.UK_postcode_error_message in the Configuration > Store App > Translations page. Image Removed

In case of lists

"create_customer" false
}

Default customer form

Default fields

By default, when the catalogue is activated, a standard form is proposed with the following fields:

This is what the default customer form looks like:

Image Added

Specific configurations on the default form

• Invert the position of the first and last names: so that the first name appears first and the last name second, you need to add the configuration "customer.invert_names" : true

{
    "customer": {
        "invert_names": true
    }
}

Image Added

• Change the list of countries:

The default form proposes the following countries: France, Belgium, Germany, Italy, Luxembourg, Spain, Switzerland, United Kingdom. An override can be made per sales channel using the configuration "countries.{sales_channel}.{list of countries}"

Country codes must be in ISO-3166 format. Logos and translations will add themselves in the Store App.

{
    "countries": {
        "sc_ois_1": [
            "FR",
            "CH"
            "GB"
        ]
    }
}

Image Added

Address autocomplete

To streamline address entry and ensure accuracy, you can activate the autocomplete module. Powered by Google, this feature provides instant address suggestions as you type, helping to automatically populate fields such as street name, number, city, and postal code. Address suggestions are limited to the country selected above.

Image Added

Add custom fields

You can take personnalisation a step further by adding custom fields to the customer form. To do this, add the required fields to the configuration customer.custom_fields.{sales_channel}.

If the fields added are to be applied to all the project's sales channels, then the field "_ALL_" must be given in the {sales_channel} part.

Here is a configuration applied to all the sales channels with ... being the structure of the custom fields that we will see below.

{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                  ...
                }
            ]
        }
    }
}

Custom fields structure

Inside the {sales_channel} entity ( or "_ALL_") there is an array of objects. Each object corresponds to a custom field to be added to the form. Here is the configuration to be entered for each custom field.

"options": [
    "MR",
    "MRS"
],

Examples

Allowed values Contact fields: title, first_name, last_name, phone_number, email, company_name, mobile_number Address fields: address_1, address_2, address_3, city, zip_code, country Custom fields: information.{custom_field}, external_id
target	string	No	Indicates whether the field should be saved in the customer structure or the address structure. By default, customer is applied. Only used for information.{custom_field} and external_id names, the others are automatically redirected to the right structure. Expand title Allowed values customer address
type	string	No	Type of the field. By default, the text type is used. Expand title Allowed values text - returns a string email - returns a string tel- returns a string password - returns a string flip-switch - returns a boolean list - returns a string or an array of string depending on the ‘multiple’ value Note If the field type is a list, then other fields will need to be configured. See below.
required	boolean	No	Indicates whether the field is mandatory or not. By default, custom fields are optional.
position_after	string	No	This key defines the name of the form element to which it must be placed after. Please note, the form element must be in the default form or declared before in the same form. It it also possible to place the element on the top of the form with the value :first. If multiple elements are placed in first position, they will be placed in the order in which they are configured. If not defined, the element form will be placed at the bottom of the form. Expand title Examples If I want my field to appear after the country field of the default form : "position_after": "country" If I want my field to appear at the top of the form : "position_after": ":first" If I want my field to appear at the bottom of the form, I leave it blank.
validation	object	No	Enables to add custom validation to the field, which will be checked when the create button is clicked. Expand title Allowed values These 3 types of validation can be configured alone or together. min_characters (int) - minimum number of characters required max_characters (int) - maximum number of characters required regex (string) - Custom regular expression used to verify the field. More information Here. error_translation_key (string) - Overrides the default translation key of the error message with a custom one if the regex is invalid. Info The error_translation_key specified here must then be translated with the pattern form.validation.{error_translation_key} from the Configuration > Store App > Translations page. Note Regexes with ‘\’ must escape by doubling it "\\" Expand title Examples Require a 5-digit postcode Code Block language json "validation": { "min_characters": 5, "max_characters": 5 } Use a custom validation for UK postcode and add a custom message if the field is invalid Code Block language json "validation": { "regex": "^([a-zA-Z]){1}([0-9][0-9]|[0-9]|[a-zA-Z][0-9][a-zA-Z]|[a-zAZ][0-9][0-9]|[a-zAZ][0-9]|[0-9][a-zAZ]){1}([ ])*([0-9][a-zA-z][a-zA-z]){1}$", "error_translation_key": "UK_postcode_error_message" } And then translate the key form.validation.UK_postcode_error_message in the Configuration > Store App > Translations page. Image Added

In case of lists

If the type of field added is a list, then additional configurations must be added inside the structure.

"options": [
    "MR",
    "MRS"
],

Examples

Edit default fields parameters

The form's default fields cannot be deleted, but they can be modified. To do this, just configure these fields in the same configuration as custom fields using the same configuration structure. It is essential that the field name configured corresponds to the name of the default fields given above.

Examples

Edit default fields parameters

The form's default fields cannot be deleted, but they can be modified. To do this, just configure these fields in the same configuration as custom fields using the same configuration structure. It is essential that the field name configured corresponds to the name of the default fields given above.

Examples

Customer creation request

Once the customer form has been completed and validated, a call will be made to the POST/customers route. If an external CRM has been configured, the call will be directly made to this external CRM.

Regarding custom information

Please note, the label of the field will be translated based on the translation key crm.<name>.

External CRM

External CRM may raised error (exemple email adress/phone number already used).
If so, project interface MUST return a 409 error including:

• field that is the field related to the conflit. Value MUST be email or phone_number

• message which is the error message to display in the interface

An external CRM may generate errors (e.g., email address or phone number already existing in the database).
In such cases, the external CRM must return a 409 error containing:

• field - form field in error

• message - error message to display

Then, the error message will be display on the form.

Customer edition

When the client is created or retrieved from the external database, it can still be modified.

• create_request_params

• update_request_params

• upsert_address_request_params

customer

• do_not_refresh_after_patch