Creating customer + controller for non-US residents

We’re facing this error in Staging: “State must be a 2-letter abbreviation.”.

The error is self-explained, and as described in the documentation, it should be: “Two-letter US state or territory abbreviation code of business’ physical address.”


  1. here’s the thing, how to handle it for countries such as Angola, where the states have 3 letters.
    reference: ISO 3166-2:AO - Wikipedia

  2. Another thing: How to handle countries with no states? For example, islands such as Åland Islands. We tried to apply the territory value with the same country ISO-2 one, but we’re facing the same “Two-letter US state or territory…” issue.

Recent test: I was able to create a customer with values from India.

So, I wondering if there are any restrictions in terms of countries you are covering

Hi @davidsonsns – we have noted the feedback for allowing more than 2-letter abbreviations for the “stateProvinceRegion” field in regards to international Controllers.

In the meantime, for countries that do not have a 2-letter abbreviation or do not have a state, province or region altogether, please use the same 2-letter ISO country code in the field. Here’s an example:

"controller": {
    "firstName": "Jane",
    "lastName": "Doe",
    "title": "CEO",
    "dateOfBirth": "1980-01-31",
    "passport": {
        "country": "AO",
        "number": "123456789"
    "address": {
        "address1": "Str 123",
        "address2": "Unit 1A",
        "city": "City name",
        "stateProvinceRegion": "AO",
        "postalCode": "12345",
        "country": "AO"

Hope that helps! Let us know if you have any questions!