Address Validation

In SCAYLE Checkout, address validation applies to shipping address for both home delivery and collection point options; as well as billing address. Since shipping information is the first step of the checkout flow, ensuring that addresses are valid and consistent is critical for a smooth order process. Validation helps prevent errors early on, improves delivery accuracy, and ensures compatibility with downstream systems such as carriers, warehouses, and payment providers.

Address Validation Options

The Checkout supports multiple levels of address validation, depending on your configuration:

Basic Regex Validation
A lightweight validation in the frontend that checks address fields (e.g., street, postal code, house number) against regex rules. This ensures formatting consistency before data is submitted.
Google Maps Autocomplete
Helps customers quickly fill in their address by suggesting valid addresses as they type, reducing manual entry and improving accuracy. This feature is free of charge and can be configured directly in the SCAYLE Panel.
Third-party Validation
Checkout can offload the validation of customer addresses to an external system from any third-party provider. This functionality can be leveraged in two ways:
- Basic address validation and rejection – external services can validate entered data and reject incorrect or incomplete addresses.
- Suggested addresses – customers are presented with a selection of corrected or standardized address options to choose from.
Detailed information is available here.

Address Form Configuration and Validation Impact

In SCAYLE Panel, tenants can configure which fields of the shipping address form are displayed to customers (e.g., title, streetHouseNumber, additional, zipCodeCity, and state).

These settings directly influence how address validation and transmission of the data to downstream systems behave. For example:

If zipCode is disabled in the SCAYLE Panel and a customer selects an address from the suggestion list, it may contain a postal code. However, because the field is hidden in the checkout form, this information will not be included in the payload.
Disabled fields are always considered empty in the checkout payload, even if external services (e.g., Google Autocomplete or third-party validation) provide the data.
Address Length Constraints: SCAYLE Panel allows configuring maximum character limits for certain fields, such as streetHouseNumber (e.g., 10–20 characters). However, when customers select an address from third-party providers, the suggested data is inserted directly into the form and may exceed the configured character limit. This bypasses the Checkout frontend input validation, making it possible to store longer values in the database.

Because of this, tenants should carefully align their form field configuration with their chosen validation method to avoid losing critical address information.

Best Practice: If you use Google Autocomplete or third-party validations, do not restrict address length in the checkout. The full address should always be captured and stored in the SCAYLE database to preserve its integrity. If tenant-specific downstream systems require shorter field lengths, those constraints should be handled outside of checkout, by implementing transformations downstream.

Google Maps Autocomplete

To enable Google Autocomplete address valitation in your checkout, go to SCAYLE Panel Settings → Checkout → Configurations and select "Shipping Step" from the dropdown:

Open Address Form tab, select Google Maps Autocomplete:

Toggle the button to enable the feature:

The address validation will be enabled for the address form for both shipping and billing addresses. To enable for Collection Points, switch to the Collection Points tab, and toggle the button to activate Google Maps Autocomplete.

How Third-party Validation Works

When a customer enters a new address during checkout — whether for home delivery or a collection point — SCAYLE Checkout sends a validation request to your configured address validation endpoint. Your system response determines the next steps:

Response Code	Description	Outcome
`200`	Suggestions Provided	If your response includes a list of suggested addresses, the customer must pick one from the list.
`204`	Address Valid	The address is confirmed as valid and can be accepted immediately.
`205`	Soft Valid	The address may be questionable, but is still accepted without correction.
`404`	Invalid Address	The address is rejected; the customer must correct or re-enter their details.

This validation happens right at the shipping information step, the very first form in the checkout flow.

If a customer selects an address from the suggestion list, the checkout automatically splits the address string and populates the corresponding fields.

In cases where the selected address is incomplete—such as a street name without a house number—the house number field will be highlighted, and the customer will be required to enter it manually before proceeding with the checkout.

For new customers and guest users, after they select a shipping address and clicks "Continue to Payment", the entered address is automatically applied as the billing address. The billing address can be modified on the payment page if needed. If the customer chooses to change the billing address, the same address validation logic used for shipping is applied to ensure accuracy and completeness.

Once you finish configuring, click on "Save" to apply the changes.

How to Implement

Reach out to your SCAYLE Account Manager to have third-party address validation activated for your checkout.

You need to provide a HTTP service that can handle the usual load of your shop and which accepts requests from the SCAYLE networks. If you want to limit incoming traffic by IP address, your SCAYLE Account Manager can provide more information about our networks.

This service needs to implement a POST endpoint according to the following schema:

Endpoint

POST {{baseUrl}}/address/validate

Request

Your endpoint needs to be able to serve the following request.

Authentication

Basic auth. The credentials for this service need to be provided to your SCAYLE Account Manager.

Headers

Parameter	Type	Details
`X-Shop-Id`	Integer	The current shop-country id

Body

Request example

Request Schema:

Parameter	Type	Required	Validation
`additional`	string	Optional	`[!-ɏ0-9 ]`
`addressCode`	string	Optional	-
`city`	string	Mandatory	`[!-ɏ0-9 ]`
`countryCode`	string	Mandatory	`[A-Z]{3}`
`county`	string	Optional	`[!-ɏ0-9 ]`
`firstName`	string	Optional	`[!-ɏ0-9 ]`
`lastName`	string	Optional	`[!-ɏ0-9 ]`
`houseNumber`	string	Optional	`[!-ɏ0-9 ]`
`street`	string	Mandatory	`[!-ɏ0-9 ]`
`zipCode`	string, integer, null	Optional	`[A-z0-9\- ]{1,12}`

Response

Your service needs to follow this specification when handling the checkout request.

Response body

Response example

Request Schema (Array):

Parameter	Type	Requirement	Details
`additional`	string	Optional	`[!-ɏ0-9 ]`
`addressCode`	string	Optional	-
`city`	string	Mandatory	`[!-ɏ0-9 ]`
`countryCode`	string	Mandatory	`[A-Z]{3}`
`county`	string	Optional	`[!-ɏ0-9 ]`
`firstName`	string	Optional	`[!-ɏ0-9 ]`
`lastName`	string	Optional	`[!-ɏ0-9 ]`
`score`	number	Optional	-
`houseNumber`	string	Optional	`[!-ɏ0-9 ]`
`street`	string	Mandatory	`[!-ɏ0-9 ]`
`zipCode`	string, integer, null	Optional	`[A-z0-9\- ]{1,12}`

Status Codes:

Response Code	Description	Response Body
`200`	request was successful, suggestions to choose from added to the response	validated address list
`204`	address is valid, it can be used right away	empty array
`205`	address is probably invalid, but it can be used right away (soft check)	empty array
`401`	unauthorized	empty
`404`	address is invalid and should not be used	empty

Address Suggestions

Regardless the validation type used, you can optionally enable a suggestion window in your checkout. When activated, after the customer enters or selects an address and clicks "Continue to Payment", a modal will open prompting the customer to select one of the validated address suggestions.

If the address suggestion is not enabled, the widget will not be shown.

Address Suggestions can be configured in SCAYLE Panel. Go to Checkout Settings → General → Configuration → Address Suggestion Configuration:

You can opt to activate the suggestion for shipping and/or billing address, and choose to allow or not the original address entered by the customer to be returned as a suggestion. Below you can find description of each of these options:

Configuration Name	Description
`addressSuggestion.shippingEnabled`	Enable/disable the address validation for the shipping address.
`addressSuggestion.billingEnabled`	Enable/disable the address validation for the billing address.
`addressSuggestion.allowOriginalAddress`	If enabled, the address provided by the customer will be returned as a suggestion. Allowing the "original" address to be used.