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

1. Include Translations - Always fetch translations for accurate multi-language support
2. Validate Country Match - Ensure state countryId matches selected country
3. Store State Code - Use state code for data consistency across systems
4. Cache by ID - Cache individual states to reduce API calls
5. Handle Missing States - Gracefully handle not found errors
6. Use Default Name Fallback - Fall back to defaultName if translation unavailable
7. Verify Data Format - Accept both numeric and path-format IDs

ID Format

The id argument accepts either format:

# 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