Get Country States

About

The countryStates query retrieves all states/provinces for a specific country. Use this query to:

• Populate state/province dropdowns in address forms
• Display available states for a selected country
• Get state translations for multi-language support
• Build location-based features and configurations
• Retrieve state codes and names for validation
• Support dynamic form field population
• Display state-specific shipping and tax information

This query returns all states for a given country with optional translations and pagination support.

Arguments

Argument	Type	Description
countryId	Int!	Numeric country ID to fetch states for.
first	Int	Number of states to return (forward pagination). Max: 100.
after	String	Pagination cursor for forward navigation.
last	Int	Number of states for backward pagination. Max: 100.
before	String	Pagination cursor for backward navigation.

Possible Returns

Field	Type	Description
id	ID!	Unique state API identifier.
_id	Int!	Numeric state ID.
code	String	State code (e.g., 'CA' for California, 'ON' for Ontario).
defaultName	String!	State name in default language.
countryId	Int!	Associated country ID.
countryCode	String!	Associated country code.
translations	StateTranslationCollection!	All state translations.
translations.edges	[Edge!]!	Translation edges.
translations.edges.node	StateTranslation!	Individual translation.
translations.edges.node.id	ID!	Translation ID.
translations.edges.node.locale	String!	Language locale code.
translations.edges.node.defaultName	String!	Translated state name.
translations.totalCount	Int!	Total translations for this state.
edges	[Edge!]!	State edges with cursors.
edges.node	CountryState!	Individual state.
edges.cursor	String!	Pagination cursor.
pageInfo	PageInfo!	Pagination information.
pageInfo.hasNextPage	Boolean!	More states available.
pageInfo.hasPreviousPage	Boolean!	Previous states available.
pageInfo.startCursor	String	First state cursor.
pageInfo.endCursor	String	Last state cursor.
totalCount	Int!	Total states for this country.

Use Cases

1. Address Form State Dropdown

Use the "For Dropdown Form" example to populate state dropdown when user selects a country.

2. Multi-Language Support

Use the "With Translations" example to display state names in user's language.

3. Large State Lists

Use the "With Pagination" example for countries with many states (e.g., US with 50 states).

Best Practices

1. Fetch on Country Selection - Load states dynamically when user selects a country
2. Cache Per Country - Cache states for each country to reduce API calls
3. Include Translations - Always fetch translations for multi-language forms
4. Handle Empty States - Some countries have no states, handle gracefully
5. Use State Code - Store state code, not just name, for consistency
6. Sort Alphabetically - Present states in alphabetical order in dropdowns
7. Minimize Fields - Request only code and name for dropdown optimization

State Codes

Common state code formats:

• US States: 2-letter codes (AL, AK, AZ)
• Canadian Provinces: 2-letter codes (ON, BC, QC)
• European Regions: Various formats
• Other Countries: May vary by country

Related Resources

• Countries - Get all countries with pagination
• Country - Get single country with states
• Country State - Get single state by ID
• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources