Get Country State
About
The countryState query retrieves detailed information about a single state/province by its ID. Use this query to:
- Fetch specific state information by ID
- Validate state information in address forms
- Get state translations for multi-language displays
- Retrieve complete state details for order processing
- Verify state belongs to correct country
- Display state information in customer dashboards
- Support state-specific business logic
- Process returns and address updates
This query returns comprehensive details about a single state including all translations.
Arguments
| Argument | Type | Description |
|---|---|---|
id | ID! | State ID (numeric or API path format, e.g., "1" or "/api/shop/country-states/1"). |
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 (e.g., 'US', 'CA'). |
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 (e.g., 'en', 'ar', 'fr'). |
translations.edges.node.defaultName | String! | Translated state name. |
translations.totalCount | Int! | Total translations for this state. |
Use Cases
1. Address Validation
Validate that selected state exists and belongs to the correct country.
2. Multi-Language Display
Show state name in customer's preferred language.
3. Order Processing
Retrieve complete state information for order confirmation and shipping.
4. State Information Display
Display state code and name in customer account or dashboard.
5. Checkout Confirmation
Confirm state information before finalizing order.
Best Practices
- Include Translations - Always fetch translations for accurate multi-language support
- Validate Country Match - Ensure state countryId matches selected country
- Store State Code - Use state code for data consistency across systems
- Cache by ID - Cache individual states to reduce API calls
- Handle Missing States - Gracefully handle not found errors
- Use Default Name Fallback - Fall back to defaultName if translation unavailable
- Verify Data Format - Accept both numeric and path-format IDs
ID Format
The id argument accepts either format:
graphql
# Numeric format
countryState(id: "1")
# API path format
countryState(id: "/api/shop/country-states/1")Both formats return identical results.
State Code Reference
State codes vary by country:
- US States: 2-letter codes (AL, AK, AZ, CA, CO, etc.)
- Canadian Provinces: 2-letter codes (ON, BC, QC, AB, etc.)
- European Regions: Varies by country
- Asian States: Varies by country
- UAE Emirates: 2-letter codes (AD, AJ, DU, etc.)
Related Resources
- Countries - Get all countries
- Country - Get single country with states
- Country States - Get all states for a country
- Shop API Overview - Overview of Shop API resources