docs
  1. SCAYLE Resource Center
  2. Developer Guides
  3. Checkout
  4. Customization
  5. Configure JSON
  6. Dynamic fields

Dynamic fields

Checkout is configured on the local shop level.

Dynamic fields

Dynamic fields are input fields (such as birthdate and phone number) as well as checkboxes (such as terms and conditions).

Use either the provided JSON file or the user interface (recommended) to configure dynamic fields.

Access JSON file to configure dynamic fields in the SCAYLE Panel

  1. Go to Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration > General Configuration.

The configuration key for each field is composed like this: dynamicFields.{area}.{field}

dynamicFields.shippingAddress.phoneNumber

Dynamic fields can appear in the following areas:

Registration

Registration
{
    "dynamicFields": {
        "register": {
            ...
        }
    }
}

Checkout as Guest

Checkout as Guest
{
    "dynamicFields": {
        "guest": {
            ...
        }
    }
}

Shipping Address

Shipping Addres
{
    "dynamicFields": {
        "shippingAddress": {
            ...
        }
    }
}

Billing Address

Billing Address
{
    "dynamicFields": {
        "billingAddress": {
            ...
        }
    }
}

Collection Poin

Collection Point
{
    "dynamicFields": {
        "collectionPoint": {
            ...
        }
    }
}

Payment Options

Payment Options
{
    "dynamicFields": {
        "paymentOptions": {
            ...
        }
    }
}

Payment Step After Payment Options

Payment Step (After Payment Options)
{
    "dynamicFields": {
        "payment": {
            ...
        }
    }
}

Payment Step Below Mobile Basket

Payment Step (Below Mobile Basket, Above 'Pay Now' Button
{
    "dynamicFields": {
        "paymentBelowMobileBasket": {
            ...
        }
    }
}

Field Types

Birth Date

Field Key: birthDate

Available Properties

  • required: true | false
    • Specify if the field is required or optional
  • minAge: number
    • Require a certain minimum age (e.g. 18)
Birth Date
{
    "birthDate": {
        "required": true,
        "minAge": 18
    }
}

Phone Number

Field Key: phoneNumber

Available Properties

  • required: true | false
    • Specify if the field is required or optional
  • mobileOnly: true | false
    • Used to only allow mobile phone numbers
  • restrictCountry: true | false
    • Used to restrict the field to phone numbers from the current country (preventing foreign phone numbers)

Even if the phone number field is not restricted to the current country, the phone number field is biased towards the current country. If no phone number country code (e.g. 0049/+49 for DE) is entered, the field will assume that it is a number from the current country. However, if you enter a phone number beginning with a country code and restrictCountry is not true, it will be accepted.

Phone number
{
    "phoneNumber": {
        "required": true,
        "mobileOnly": true,
        "restrictCountry": false
    }
}

Logistics Phone Number

Field Key: logisticsPhoneNumber

Available Properties

  • required: true | false
    • Specify if the field is required or optional
  • mobileOnly: true | false
    • Used to only allow mobile phone numbers
  • restrictCountry: true | false
    • Used to restrict the field to phone numbers from the current country (preventing foreign phone numbers)

Even if the phone number field is not restricted to the current country, the phone number field is biased towards the current country. If no phone number country code (e.g. 0049/+49 for DE) is entered, the field will assume that it is a number from the current country. However, if you enter a phone number beginning with a country code and restrictCountry is not true, it will be accepted.

Logistics Phone Number
{
    "logisticsPhoneNumber": {
        "required": true,
        "mobileOnly": true,
        "restrictCountry": false
    }
}

Tax ID

Field Key: taxId

Available Properties

  • The general field validation properties can be used (see Field Validation).

This is used if there is a need to set a tax id, usually for bigger orders or to comply with a certain country's laws.

Tax ID
{
    "taxId": {
        "required": true
    }
}

Carrier Customer ID

Field Key: carrierCustomerId

Available Properties

  • The general field validation properties can be used (see Field Validation).

This is used to set a carrier specific customer ID (e.g. DHL Postnummer)

Carrier customer ID 
{
    "carrierCustomerId": {
        "required": true,
        "minLength": 6,
        "maxLength": 10,
        "format": "^\\d+$"
    }
}

carrierConsent

Available properties

  • name must be set to "carrierConsent" or else the field will not be displayed in the form.
  • initialValue is used to prefill this field. Set to "true" if you want the field prefilled by default, "false" if not.
  • required is used to specify if consent is mandatory. Set to "true" if it is, "false" if not.
{
    "name": "carrierConsent",
    "initialValue": false,
    "i18nKeys": { "label": "payment.carrierConsent" }
},

Checkboxes

checkboxes

Available Properties

  • required is used to specify if the field is required or optional.
  • name is used to specify the checkbox name. For newsletter sign up set this to newsletterSignUp to enable the respective API handling.
  • i18nKeys.label is used to specify the translation key of the checkbox label.
  • i18nKeys.headline is used to specify the translation key of the checkbox headline (optional, only needs to be set, if there should be a headline).

Any number of Checkboxes (e.g. newsletter sign up, terms and conditions / privacy policy consent)

Checkboxes
{
    "checkboxes": [
        {
            "name": "newsletterSignUp",
            "i18nKeys": { "label": "auth.newsletterSignUp" }
        }
    ]
}

Texts

Field Key: texts

Available Properties

  • name is used to specify the text name.
  • i18nKeys.label is used to specify the translation key of the text.
  • i18nKeys.headline is used to specify the translation key of the text headline (optional, only needs to be set, if there should be a headline).

Any number of simple Text Paragraphs (e.g. legal hints, ...) (texts)

The config key for each field is composed like this: dynamicFields.{area}.{field} (Example: dynamicFields.shippingAddress.phoneNumber)

Texts

Available Properties

  • name is used to specify the text name.
  • i18nKeys.label is used to specify the translation key of the text.
  • i18nKeys.headline is used to specify the translation key of the text headline (optional, only needs to be set, if there should be a headline).

Any number of simple Text Paragraphs (e.g. legal hints)

{
    "texts": [{ "name": "term_conditions_info", "i18nKeys": { "label": "custom1" } }]
}

Conditions

Each dynamic field can be conditionally enabled/disabled (shown/hidden) and conditionally required/optional. Depending on the area a field is configured in, you can define conditions based on the following criteria:

Carrier Group Key

Condition Key: carrierGroupKey

Available Sections

  • Shipping Address: shippingAddress
  • Collection Point: collectionPoint
  • Payment: payment
  • Payment Below Mobile Basket: paymentBelowMobileBasket
{
    "required": { "carrierGroupKey": ["dhl"] }
}

This example only makes the field required if the carrierGroupKey is dhl

Shipping Option Key

Condition Key: shippingOptionKey

Available Sections

  • Shipping Address: shippingAddress
  • Collection Point: collectionPoint
  • Payment: payment
  • Payment Below Mobile Basket: paymentBelowMobileBasket
{
    "required": { "shippingOptionKey": ["de_dhl_express_normal", "de_dhl_express_reduced"] }
}

This example only makes the field required if the shippingOptionKey is de_dhl_express_normal or de_dhl_express_reduced.

Collection Point Type

Condition Key: collectionPointType

Available Sections

  • Collection Point: collectionPoint
{
    "required": { "collectionPointType": ["parcel_locker"] }
}

{
    "countryOverwrites": {
        "SA": {
            "currency": "SAR",
            "dynamicFields": {
                "payment": {
                    "logisticsPhoneNumber": { "required": true },
                    "taxId": { "conditions": { "required": { "minBasketTotal": 100000 } } }
                },
                "billingAddress": { "birthDate": { "required": false } }
            }
        }
    }
}

Payment Option Key

Condition Key: paymentOptionKey

Available Sections

  • Payment Options: paymentOptions
  • Payment: payment
  • Payment Below Mobile Basket: paymentBelowMobileBasket
{
    "enabled": { "paymentOptionKey": ["klarna_paynow_direct_bank_transfer"] }
}

This example only shows the field if the paymentOptionKey is klarna_paynow_direct_bank_transfer

Shipping Country

Condition Key: shippingCountry

Available Sections

  • Shipping Address: shippingAddress
{
    "enabled": { "shippingCountry": ["DE"] }
}

This example only shows the field if the shippingAddress is DE (Germany).

Billing Country

Condition Key: billingCountry

Available Sections

  • Billing Address: billingCountry
{
    "enabled": { "billingCountry": ["DE"] }
}

This example only shows the field if the billingCountry is DE (Germany).

Minimum Basket Total

Condition Key: minBasketTotal

{
    "taxId": { "conditions": { "required": { "minBasketTotal": 100000 } } }
}

This is used to set a limit if orders are over a certain value (e.g. for customs regulations)

You cannot create your own translation keys for texts and checkboxes. You can use payment.termsAndPrivacy or auth.newsletterSignUp or, if these don't match your use case, you can use one of the keys custom1 to custom10.

Advanced Examples

Check for multiple conditions

{
    "required": { "carrierGroupKey": ["dhl"], "collectionPointType": ["parcel_locker"] }
}

The above example would only make the field required if the carrierGroupKey is dhl AND the collectionPointType is parcel_locker.

Hence, conditions for different fields are always linked with a logical AND. You can also specify multiple values to match against for the same field. In that case, the values are linked with a logical OR (meaning one matching value is enough, which is logical because you can't have multiple carriers or payment methods selected at the same time).

Collect tax ID for big orders

Customers need to provide their ID in case they place orders over a certain value (1.000 SAR for SA, 450 ILS for IL). This is required for customs regulations:

{
    "countryOverwrites": {
        "SA": {
            "currency": "SAR",
            "dynamicFields": {
                "payment": {
                    "logisticsPhoneNumber": { "required": true },
                    "taxId": { "conditions": { "required": { "minBasketTotal": 100000 } } }
                },
                "billingAddress": { "birthDate": { "required": false } }
            }
        }
    }
}

Collect phone number for certain shipping options

Show the logisticsPhoneNumber only for German shops (DE) in the payment area if any shippingOptions like de_dhl_express_normal, de_dhl_express_reduced, de_dhl_express_usa_reduced, etc. were selected:

{
    "countryOverwrites": {
        "DE": {
            "dynamicFields": {
                "payment": {
                    "logisticsPhoneNumber": {
                        "required": true,
                        "conditions": {
                            "enabled": {
                                "shippingOptionKey": [
                                    "de_dhl_express_normal",
                                    "de_dhl_express_reduced",
                                    "de_dhl_express_usa_reduced",
                                    "de_dhl_express_usa_normal",
                                    "de_dhl_express_free",
                                    "de_combined_dhl_shipper",
                                    "de_combined_dhl_shipper_free",
                                    "de_combined_hermes_shipper",
                                    "de_combined_hermes_shipper_free"
                                ]
                            }
                        }
                    }
                }
            }
        }
    }
}
Sample configuration
{
    "register": {
        "checkboxes": [
            {
                "name": "newsletterSignUp",
                "i18nKeys": { "label": "auth.newsletterSignUp" }
            }
        ]
    },
    "guest": {
        "checkboxes": [
            {
                "name": "newsletterSignUp",
                "i18nKeys": { "label": "auth.newsletterSignUp" }
            }
        ]
    },
    "shippingAddress": {
        "birthDate": {
            "required": true,
            "minAge": 18
        },
        "phoneNumber": {
            "required": true
        },
        "logisticsPhoneNumber": {
            "required": true,
            "conditions": {
                "enabled": { "carrierGroupKey": ["dhl"] }
            }
        }
    },
    "collectionPoint": {
        "carrierCustomerId": {
            "required": true,
            "format": "^//d+$",
            "conditions": {
                "enabled": { "carrierGroupKey": ["dhl"] }
            }
        }
    },
    "paymentOptions": {
        "birthDate": {
            "required": true,
            "minAge": 18,
            "conditions": {
                "enabled": { "paymentOptionKey": ["computop_creditcard"] }
            }
        },
        "phoneNumber": {
            "required": true,
            "conditions": {
                "enabled": { "paymentOptionKey": ["klarna_paynow_direct_bank_transfer"] }
            }
        }
    },
    "payment": {
        "checkboxes": [
            {
                "name": "newsletterSignUp",
                "i18nKeys": { "label": "auth.newsletterSignUp" }
            },
            {
                "name": "termsAndPrivacy",
                "required": true,
                "i18nKeys": { "label": "payment.termsAndPrivacy" }
            }
        ]
    }
}
Previous
Currency, dates & name formats
Next up
Email and password custom rules