Versions Compared

Version Old Version 2 New Version Current
Changes made by

Thibault Galharret

Thibault Galharret

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Table of Contents
stylenone

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

Expand
titleValidation rule

A valid email format is required

Phone Number

tel

Yes

Yes

Expand
titleValidation rule

The phone index corresponding to the store's country is automatically proposed. It can, however, be changed manually.
Validation is then carried out according to the selected index, respecting the national rules.

Country

list

Yes

Yes

Expand
titleValidation rule

The country code corresponding to the store's country is automatically selected. It can, however, be changed manually.

Note

By default, the list proposes the following countries: France, Belgium, Germany, Italy, Luxembourg, Spain, Switzerland, United Kingdom.

This list can be overwritten, see section below.

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 Modified

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 in the Configuration > Store App > Pages > Catalog > Specific settings page in the Options section.

    Code Block
    {
    "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}" 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.

Code Block
{
    "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.

autocomplete_doc.gifImage Added

Please note:

This feature requires the activation of an additional module. To activate it, a specific contractual agreement is required, involving an additional cost per order placed through Order In Store.

For more information, please reach out to our sales team or your account manager. 

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}[{custom_fields_structure}] in the Configuration > Store App > Pages > Catalog > Specific settings page in the Options section.

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.

Code Block
languagejson
{
    "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.

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>

Expand
titleAllowed 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
titleAllowed values

  • customer

  • address

type

string

No

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

Expand
titleAllowed 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
titleExamples

  • 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
titleAllowed 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
languagejson
"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
languagejson
"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"
}

...

Fields if the field is a list

...

options

...

initial_value

...

multiple

...

searchable

Request entries

Regarding the address:

...

address_1 - sent in the customer.addresses.[0].lines.[0] field of the POST /customers query

...

address_2 - sent in the customer.addresses.[0].lines.[1] field of the POST /customers query

...

city - sent in the customer.addresses.[0].city field of the POST /customers query

...

zip_code - sent in the customer.addresses.[0].zip_code field of the POST /customers query

...

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.
Field
Type
Mandatory
Description
options
array[string]
Yes
List of values displayed in the drop down.
Options inside will be translated with the key crm.information._{name}_options.{option}
 Expand
titleExample
List of options for the title custom field
 Code Block
"options": [
    "MR",
    "MRS"
],
multiple
bool
No
Indicates if multiple selection can be done.
searchable
bool
No
Indicates if drop down elements are searchable.
initial_value
string
No
Indicates the pre-selected option. 
Examples
 Expand
titleAdd the ‘civility’ field as a list at the top of the form
 Code Block
{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                    "name": "title",
                    "options": [
                        "Mr",
                        "Mrs",
                        "Miss",
                        "Dr",
                        "Sir"
                    ],
                    "position_after": ":first",
                    "required": true,
                    "type": "list"
                    "multiple": false,
                    "initial_value": "Mr"
                }
            ]
        }
    }
}
 Image Added
 Expand
titleAdd a button at the bottom of the form to accept the terms and conditions of sale
 Code Block
{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                    "initial_value": true,
                    "name": "information.terms_of_sales",
                    "position_after": "zip_code",
                    "required": true,
                    "type": "flip-switch"
                }
            ]
        }
    }
}
 Image Added
 Expand
titleAdd a ‘birthday’ field after the first name with validation of the date format
 Code Block
{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                    "name": "information.birthday",
                    "position_after": "phone_number",
                    "required": false,
                    "type": "text",
                    "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"
}
                }
            ]
        }
    }
}
 Image Added
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.
 Note
Overloading a default field removes its mandatory and validation options. To make it mandatory again, for example, specify "required": true
Examples
 Expand
titleAdd a regex to check English postcodes in the default ‘zipcode’ field 
 Code Block
{
    "customer": {
        "custom_fields": {
            "sc_uk": [
                {
                    "name": "zip_code",
                    "required": true,
                    "validation": {
                        "error_translation_key": "UK_postcode_error_message",
                        "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}$"
                    }
                }
            ]
        }
    }
}
 Image Added
 Expand
titleAdd a 30-character limit to the default ‘first_name’ field 
 Code Block
{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                    "name": "first_name",
                    "required": true,
                    "type": "text",
                    "validation": {
                        "max_characters": 30
                    }
                }
            ]
        }
    }
}
 Image Added
 Expand
titleMake the default ‘phone_number’ field optional
 Code Block
{
    "customer": {
        "custom_fields": {
            "_ALL_": [
                {
                    "name": "phone_number",
                    "required": false,
                    "type": "tel"
                }
            ]
        }
    }
}
 Image Added
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. 
 Expand
titleMapping between form fields and the POST/customers route
Form field
POST/customer field
title
customer.contact.title AND customer.addresses.[0].contact.title
first_name 
customer.contact.first_name AND customer.addresses.[0].contact.first_name
last_name
customer.contact.last_name AND customer.addresses.[0].
...
contact.last_name
email
customer.contact.email AND customer.addresses.[0].contact
...
title
...
first_name 
...
last_name
.email
phone_number 
customer.contact.phone_number AND customer.addresses.[0].contact.phone_number
...
email
...
company_name
mobile_number
customer.contact.mobile_number AND customer.addresses.[0].contact.mobile_number
Regarding custom information
...
company_name
customer.contact.company_name AND customer.addresses.[0].
...
contact.company_name
external_id
...
customer.external_id
...
Please note, the label of the field will be translated based on the translation key crm.<name>.
...
Key
...
Mandatory
...
Type 
...
Allowed values
...
Default value
...
Description
...
target
...
No
...
string
...
customer
address
...
customer
...
This key defines which form is targetted: customer or address. By default if target is not given, customer is applied.
Only useful for information.{custom_field} and external_id fields
...
type
...
No
...
string
...
text, email, tel, password, flip-switch,  list
...
text
...
This key defines the HTML element is used.
  • text is for HTML input type text. Value returned will be a string
  • email is for HTML input type email. Value returned will be a string
  • tel is for HTML input type tel. Value returned will be a string
  • password is for HTML input type password. Value returned will be a string
  • flip-switch is for toggle switch (yes/no). Value returned will be boolean true for YES, and false for NO
  • list is for drop-down. If key multiple:false, then value returned will be a string. If key multiple:true, then value returned will be an array of string
...
options
...
No
...
string[]
...
/
...
/
...
This key is usable only if key:list
It defines values inside dropdown.
Content inside will be translated based on translation keys crm.information._<list_name>_options.<option_value> where <list_name> is the name of the list that will use options, and <option_value> is the value of the option.
...
initial_value
...
No
...
string / bool
...
/
...
/
...
This key is usable ONLY if key:list
It defines which value will be preselected.
If multiple:true, use comma ',' to separate values.
...
multiple
...
No
...
bool
...
/
...
false
...
This key is usable ONLY if key type:list. 
It defines if multiple selection can be done.
If key multiple:false, then value returned will be a string. If key multiple:true, then value returned will be an array of string. 
...
searchable
...
No
...
bool
...
/
...
false
...
This key is usable only if key type:list
It defines if dropdown elements are searchable.
...
required
...
No
...
bool
...
/
...
false
...
This key force completion to validate form.
true to force.
...
position_after
...
No
...
string
...
/
...
/
This key defines the name of the form element to which it must be placed after. 
":first" is a keyword to place the element on the top of the form.
If multiple elements are with position_after::first, they will be placed on the top of the form in the order of their declaration (first declared will be on the top).
Element which is named in this key MUST have been declared before in the same form as this one.
...
address_1
customer.addresses.[0].lines.[0]
address_2
customer.addresses.[0].lines.[1]
address_3
customer.addresses.[0].lines.[3]
city
customer.addresses.[0].city
zip_code
customer.addresses.[0].zip_code
country
customer.addresses.[0].regions.country.code
information.{custom_field}
If the target configuration is customer: customer.contact.information.{custom_field}
If the target configuration is address: customer.addresses.[0].information.{custom_field}
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.