Skip to main content
Version: 3.0 (beta)

Address validation

Introduction#

Address format varies between each country. Saleor has a backend side validation library that helps you to gather data required by postal services.

note

Validation is only performed on the format of address data. To check if the address exists or get the address auto-complete, use services like Shippo or Loqate.

Validation rules#

Using the addressValidationRules query, API clients can fetch validation rules depending on the selected country. Based on the ruleset, some address fields can be hidden (e.g. countryArea). Saleor Core uses Google i18n address under the hood, with a ruleset from Google Address Data.

query {  addressValidationRules(countryCode: PL) {    countryName    allowedFields    requiredFields    countryAreaType  }}

Response:

{  "data": {    "addressValidationRules": {      "countryName": "POLAND",      "allowedFields": [        "city",        "streetAddress1",        "postalCode",        "streetAddress2",        "companyName",        "name"      ],      "requiredFields": [        "streetAddress1",        "city",        "postalCode"      ],      "countryAreaType": "province"    }  }}

Depending on the country, not all allowedFields fields are necessary. Nevertheless, additional info could be helpful for postal services.

Setting up an address using API#

As example of address validation API, we are going to set the billing address in the checkout. An operation can be made with checkoutBillingAddressUpdate:

mutation {  checkoutBillingAddressUpdate(    billingAddress: {      country: PL      firstName: "John"      lastName: "Smith"      streetAddress1: "ul. Tęczowa 7"      postalCode: "53-030"      city: "Wroclaw"    }    token: "58f4ca17-9c6f-437b-8204-beb47bbee364"  ) {    checkout {      billingAddress {        firstName        lastName        streetAddress1        city        postalCode      }    }    errors {      field      message      code    }  }}

Successful response:

{  "data": {    "checkoutBillingAddressUpdate": {      "checkout": {        "billingAddress": {          "firstName": "John",          "lastName": "Smith",          "streetAddress1": "ul. Tęczowa 7",          "city": "WROCLAW",          "postalCode": "53-030"        }      },      "errors": []    }  }}

Errors#

Let's create an example of address validation errors. The address below is missing a few fields and has the wrong postal code:

mutation {  checkoutBillingAddressUpdate(billingAddress:{    country:PL,    firstName: "John",    lastName: "Smith",    postalCode: "Wrong Code"  }, token: "58f4ca17-9c6f-437b-8204-beb47bbee364"){    errors {      field      message      code    }  }}

Response:

{  "data": {    "checkoutBillingAddressUpdate": {      "errors": [        {          "field": "city",          "message": "This field is required.",          "code": "REQUIRED"        },        {          "field": "postalCode",          "message": "This value is not valid for the address.",          "code": "INVALID"        },        {          "field": "streetAddress1",          "message": "This field is required.",          "code": "REQUIRED"        },        {          "field": "streetAddress2",          "message": "This field is required.",          "code": "REQUIRED"        }      ]    }  }}

Each field is validated separately, and each issue has a corresponding error code:

  • postalCode with a wrong format throws the INVALID error
  • missing fields mentioned in requiredFields throws the REQUIRED error