US addresses require a state (administrativeArea) in addition to the standard fields. The house number comes before the street name, and postal codes (ZIP codes) are 5 digits with an optional 4-digit extension.
{
"countryCode": "US",
"postalCode": "94105",
"addressLines": ["123 Market Street", "Suite 400"],
"locality": "San Francisco",
"administrativeArea": "CA"
}| Field | Required | Description |
|---|---|---|
countryCode | Yes | Always "US" |
postalCode | Yes | 5-digit ZIP code (optionally with +4 extension) |
addressLines | Yes (for shipment) | Index 0: number, street name, and type |
locality | Yes (for shipment) | City |
administrativeArea | Yes | 2-letter state abbreviation (e.g., "CA", "NY", "TX") |
subLocality | No | Neighborhood — rarely needed |
- Format: 5 digits, optionally followed by a dash and 4 more digits
- Regex:
^\d{5}(-\d{4})?$ - Examples:
"94105","94105-1234" - Sanitization: The API strips all characters except digits and dashes
The 4-digit ZIP+4 extension improves delivery precision but is not required. Most checkouts collect only the 5-digit ZIP code.
The administrativeArea field is required for the United States. It must be a valid 2-letter USPS state abbreviation.
All 50 states, the District of Columbia, and US territories are supported:
- States:
AL,AK,AZ,AR,CA,CO,CT,DE,FL,GA,HI,ID,IL,IN,IA,KS,KY,LA,ME,MD,MA,MI,MN,MS,MO,MT,NE,NV,NH,NJ,NM,NY,NC,ND,OH,OK,OR,PA,RI,SC,SD,TN,TX,UT,VT,VA,WA,WV,WI,WY - Federal district:
DC - Territories:
AS,GU,MH,FM,MP,PW,PR,VI - Military:
AA,AE,AP
The address form endpoint returns administrativeArea as a select field type with all valid options pre-populated.
The house number comes before the street name, followed by the street type.
| Scenario | addressLines value |
|---|---|
| Standard | ["123 Market Street"] |
| With suite | ["123 Market Street", "Suite 400"] |
| With apartment | ["456 Oak Avenue", "Apt 2B"] |
| PO Box | ["PO Box 1234"] |
- Apartment, suite, unit, and floor numbers go on the second address line
- Street types (Street, Avenue, Boulevard, etc.) are part of the first line
The locality field is the city.
- Example:
"San Francisco","New York","Austin" - The city can be pre-filled from the ZIP code using the address form endpoint
| Mistake | Problem | Fix |
|---|---|---|
Missing administrativeArea | Required for US addresses | Include the 2-letter state code |
"administrativeArea": "California" | Full state name instead of abbreviation | Use the abbreviation: "CA" |
"addressLines": ["Market Street 123"] | Street before number | US uses number-first: ["123 Market Street"] |
"postalCode": "94,105" | Comma in ZIP code | The API strips non-digit characters automatically |