Address Validation

Address format varies between each country. Saleor has a backend validation library that helps you 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 can be helpful for postal services.

Valid address items extension

Saleor gives an option to extend the ruleset from Google Address Data and process custom address names. There is a VALID_ADDRESS_EXTENSION_MAP embedded in core repository, which can be utilized to link custom names with the valid ones.

Ie. Dublin is an invalid countryArea in accordance to Google Address Data ruleset. The correct value is Co. Dublin. By providing a proper mapping, the value Dublin will be recognized as a valid country area and converted to Co. Dublin.

Setting up the address using the API

As an example of the address validation API, we will set the billing address in the checkout. The 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
    }
  }
}

Expand ▼

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"
        }
      ]
    }
  }
}

Expand ▼

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

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

Skipping the address validation

Since version 3.19, Saleor can skip part of address validation. To enable this, set the skipValidation flag to true in the AddressInput. This disables format validation for all fields except the country and phone. Saleor will still validate required address items and will try to normalize valid fields.

info

Using the skipValidation flag may require extra permissions.

• checkoutCreate - requires HANDLE_CHECKOUT and AUTHENTICATED_APP permissions.
• accountAddressCreate and accountUpdate - require IMPERSONATE_USER and AUTHENTICATED_APP permissions.
• accountAddressUpdate - requires MANAGE_USERS and AUTHENTICATED_APP permissions.

warning

Providing an invalid address may cause Saleor to be unable to complete some external requests. For example, an incorrect address could result in errors in the tax app response and an inability to create an order.