I originally posted this article to x.com on September 21, 2010. Since that time, x.com has been repurposed, and my posts have been taken down. I have reposted this here for informational and historical purposes.
I know, both first and second-hand, that there is a lot of confusion over exactly what data needs to be passed for addresses in foreign countries. In this post, I’ll try to lay out each country’s specific rules. This is going to be a work-in-progress, as I don’t anticipate having every country shown on this list right off the bat, but I hope that I’m doing some good by putting it out there.
Please be aware that much of this information was gathered from internal sources, and although I believe it to be correct, I haven’t had time to test out every country to make sure that it’s 100% correct. So please, if you find something here that turns out to be incorrect, please let me know so that I can get it fixed! (I’d rather be right than wrong any day!) Just leave a comment at the bottom of the page.
Any time I make reference to fields such as STREET, STREET2, CITY, STATE, ZIP, and COUNTRYCODE, please assume that they will correspond to the fields for the specific API call and language (NVP or SOAP) that you are using.
Also, any time I specify the format for ZIP, N should be a numeric character (0-9), and X should be an alphabetic character (A-Z).
Lastly, you may not be required to pass any address information at all. If a particular country is giving you problems, try running an API call without passing any address information at all — if the transaction succeeds, then you can work around the issue by simply not passing the address.
P.S. — There’s been some attempts before to compile information like this. See here (link broken) and here (link broken) for more information. There’s also a list of country codes (we use the ISO 3166-1 alpha-2 codes) here or here.
Australia
- You need to pass STREET, CITY, and ZIP. STATE is optional. If you do supply a STATE, it should be the full state name (e.g., Northern Territory).
- ZIP should be specified as NNNN.
Canada
- You need to pass STREET, CITY, STATE, and ZIP.
- STATE should be set to the province’s two-character abbreviation (ex.: QC).
- ZIP should be specified as XNXNXN.
France
- You need to pass STREET, CITY, and ZIP. STATE is not required.
- ZIP should be specified as NNNNN.
Germany
- You need to pass STREET, CITY, and ZIP. STATE is not required.
- ZIP should be specified as NNNNN.
Italy
- You need to pass STREET, CITY, and ZIP. STATE is optional. If you do supply a STATE, it should be the two-character province abbreviation (ex.: GE).
- ZIP should be specified as NNNNN.
Japan
- You need to pass STREET, CITY, and ZIP. STATE is required only for shipping addresses (if you specify one). It is not required for billing addresses.
- The address should be romanized.
- STATE should be set to the full prefecture name (ex.: Tokyo).
- CITY should be set to the municipality.
- STREET should be the location within the municipality (e.g., the rest of the address).
- ZIP should be specified as NNN-NNNN.
- For DoDirectPayment calls on the Sandbox, omit the state, as anything else causes an error. Leave the shipping address off altogether. (If you’re really adamant about testing it with a state and/or shipping address, set STATE to JP-40.)
As an example, the address of the Tokyo Central Post Office is:
Tokyo Central Post Office
5-3, Yaesu 1-Chome
Chuo-ku, Tokyo 100-8994
In this scenario, I would set my variables accordingly:
- STREET=”5-3, Yaesu 1-Chome”
- CITY=”Chuo-ku”
- STATE=”Tokyo”
- ZIP=”100-8994″
Spain
- You need to pass STREET, CITY, and ZIP. STATE is optional. If you do pass a STATE, it should be the full province name, with accented characters translated into their non-accented equivalents (ex.: Avila).
- ZIP should be specified as NNNNN.
Sweden
- You need to pass STREET and CITY. STATE is not required. ZIP is optional.
- If you do pass a ZIP, it should be specified as NNNNN.
United Kingdom
- You only need to pass STREET, CITY, and ZIP. STATE is optional. If you do pass a STATE, it should be the county name (ex.: West Sussex).
- Make sure you set COUNTRYCODE to GB, not UK! (If you look at ISO 3166-1, the United Kingdom specifically reserved it so that no one else would use it, but it’s still not their official country code.) Passing UK results in a nasty user experience for your buyers.
- There’s not a good way to describe the format for ZIP, so I’ll just say go look at the Wikipedia article.
United States
- You need to pass STREET, CITY, STATE, and ZIP.
- STATE should be the state’s two-character abbreviation (ex.: NY)
- ZIP should be either the 5 or 9-digit ZIP code, in the format NNNNN, NNNNN-NNNN, NNNNNNNNN, or NNNNN NNNN.