Address validation

Overview

Checkout can offload the validation of customer addresses to an external system. This functionality can be leveraged in two ways:

• Basic address validation and rejection
• Providing a selection of suggested addresses to choose from

This page will guide you on how to set up an API that can be integrated with Checkout.

How it works

When a customer inputs a new address during checkout, Checkout sends a request to your system. The response dictates the subsequent actions:

• If a list of suggestions is returned, the customer must select one.
• If the requested address is valid, it can be stored immediately without confirmation.
• If the address is deemed invalid, it should be corrected.

Refer to the status codes overview for further details.

How to implement

You need to provide a http service that can handle the usual load of your shop and which accepts requests from the SCAYLE 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

Body

Request example

json

Copy

{
    "additional": "3d level",
    "addressCode": "20459 3d Level right",
    "city": "Hamburg",
    "countryCode": "DEU",
    "county": "Hamburg",
    "firstName": "Anna",
    "houseNumber": "12",
    "lastName": "Doe",
    "street": "Mainstr.",
    "zipCode": "20459"
}

Request schema

• additional string ([!-ɏ0-9 ]) (optional)
• addressCode string (optional)
• city string ([!-ɏ0-9 ])
• countryCode string ([A-Z]{3})
• county string ([!-ɏ0-9 ]) (optional)
• firstName string ([!-ɏ0-9 ]) (optional)
• houseNumber string ([!-ɏ0-9 ]) (optional)
• lastName string ([!-ɏ0-9 ]) (optional)
• street string ([!-ɏ0-9 ])
• zipCode string,integer,null (optional)

Response

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

Response body

Response example

json

Copy

[
  {
    "city": "Hamburg",
    "countryCode": "DEU",
    "firstName": "Anna",
    "houseNumber": "10",
    "lastName": "Doe",
    "score": 0.9,
    "street": "Domstr.",
    "zipCode": "20095"
  },
  {
    "city": "Hamburg",
    "countryCode": "DEU",
    "firstName": "Anna",
    "houseNumber": "12",
    "lastName": "Doe",
    "score": 0.6,
    "street": "Domstr.",
    "zipCode": "20095"
  }
]

Response schema

• array
  • additional string ([!-ɏ0-9 ]) (optional)
  • addressCode string (optional)
  • city string ([!-ɏ0-9 ])
  • countryCode string ([A-Z]{3})
  • county string ([!-ɏ0-9 ]) (optional)
  • firstName string ([!-ɏ0-9 ]) (optional)
  • houseNumber string ([!-ɏ0-9 ]) (optional)
  • lastName string ([!-ɏ0-9 ]) (optional)
  • score number (optional)
  • street string ([!-ɏ0-9 ])
  • zipCode string ([A-z0-9\- ]{1,12})

Status Codes:

Enable address validation in the Checkout

Use the SCAYLE Panel to enable address validation in the Checkout.

1. In the SCAYLE Panel, go to Shops > [Shop] > Storefront > Checkout Settings > Checkout Frontend Configuration.
2. Select Address Form.