State codes

The HLC API accepts standard two-letter state and province codes for US and Canadian addresses in order fulfillment and shipping operations.

Overview

Address validation requires proper state/province codes that correspond to the specified country. The API supports fulfillment to most US states and all Canadian provinces using ISO 3166-2 two-letter codes.

Supported Regions

United States

The following US state and territory codes are accepted:

Continental US: AL, AR, AZ, CA, CO, CT, DE, DC, FL, GA, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VA, VT, WA, WI, WV, WY

US Territories: AS (American Samoa), FM (Micronesia), GU (Guam), MH (Marshall Islands), MP (Northern Mariana Islands), PR (Puerto Rico), PW (Palau), VI (US Virgin Islands)

Canada

All Canadian provinces and territories are supported for fulfillment:

API Implementation

Creating Orders with State Codes

Include the two-letter state/province code in the shipping address:

const apiUrl = 'https://api.hlc.bike/us/v4.1'
const apiKey = process.env.HLC_API_KEY

const response = await fetch(`${apiUrl}/Orders/Create/Fulfillment`, {
  method: 'POST',
  headers: {
    ApiKey: apiKey,
    'Content-Type': 'application/json',
    language: 'en',
  },
  body: JSON.stringify({
    items: [{ variantNo: '020056-07', quantity: 2 }],
    shippingAddress: {
      name: 'John Doe',
      address1: '123 Main St',
      city: 'Springfield',
      state: 'IL', // Two-letter state code
      zip: '62701',
      country: 'US',
    },
  }),
})

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${response.statusText}`)
}

const order = await response.json()

Canadian Address Example

const response = await fetch(`${apiUrl}/Orders/Create/Fulfillment`, {
  method: 'POST',
  headers: {
    ApiKey: apiKey,
    'Content-Type': 'application/json',
    language: 'en',
  },
  body: JSON.stringify({
    items: [{ variantNo: '861070-L-001', quantity: 1 }],
    shippingAddress: {
      name: 'Jane Smith',
      address1: '456 Rue Principale',
      city: 'Montreal',
      state: 'QC', // Quebec province code
      zip: 'H3A 1A1',
      country: 'CA',
    },
  }),
})

const order = await response.json()

Address Validation

State Code Validation Rules

The API performs the following validations during order creation:

1. Format validation: State code must be exactly 2 uppercase letters
2. Supported code validation: Code must be in the list of supported regions
3. Country correspondence: State code must be valid for the specified country
4. Shipping restrictions: Orders to restricted regions (AK, HI, PR) are rejected

Error Responses

Invalid state codes result in HTTP 400 errors with descriptive messages:

{
  "error": "Invalid state code",
  "message": "State code 'XX' is not supported for country 'US'",
  "field": "shippingAddress.state"
}