Get Countries

About

The countries query retrieves all available countries and their states/provinces configured in your Bagisto store. Use this query to:

• Build country/region selector dropdowns for addresses
• Display available shipping destinations
• Create address form fields with country and state options
• Implement multi-language country names and state names
• Display shipping country restrictions
• Build geographic-based features and configurations
• Populate checkout address forms with country and state data
• Support currency and language selection based on country

This query returns comprehensive country data including all states, translations for countries and states, and pagination support for large country lists.

Arguments

Argument	Type	Description
first	Int	Number of countries to return (forward pagination). Max: 100.
after	String	Pagination cursor for forward navigation.
last	Int	Number of countries for backward pagination. Max: 100.
before	String	Pagination cursor for backward navigation.

Possible Returns

Field	Type	Description
id	ID!	Unique country API identifier.
_id	Int!	Numeric country ID.
code	String!	ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'AE').
name	String!	Country name in default language.
states	CountryStateCollection!	States/provinces for this country.
states.edges	[Edge!]!	State edges with cursors.
states.edges.node	CountryState!	Individual state information.
states.edges.node.id	ID!	State API identifier.
states.edges.node._id	Int!	Numeric state ID.
states.edges.node.code	String	State code (e.g., 'CA' for California).
states.edges.node.defaultName	String!	State name in default language.
states.edges.node.countryId	Int!	Associated country ID.
states.edges.node.countryCode	String!	Associated country code.
states.edges.node.translation	CountryStateTranslation!	State translation in current locale.
states.edges.node.translation.id	ID!	Translation identifier.
states.edges.node.translation._id	Int!	Numeric translation ID.
states.edges.node.translation.countryStateId	Int!	Associated state ID.
states.edges.node.translation.locale	String!	Language locale code.
states.edges.node.translation.defaultName	String!	State name in locale language.
states.edges.node.translations	StateTranslationCollection!	All state translations.
states.edges.node.translations.edges	[Edge!]!	Translation edges.
states.edges.node.translations.edges.node.id	ID!	Translation ID.
states.edges.node.translations.edges.node.locale	String!	Locale code.
states.edges.node.translations.edges.node.defaultName	String!	Translated state name.
states.pageInfo	PageInfo!	Pagination info for states.
states.pageInfo.hasNextPage	Boolean!	More states available.
states.pageInfo.hasPreviousPage	Boolean!	Previous states available.
states.pageInfo.startCursor	String	First state cursor.
states.pageInfo.endCursor	String	Last state cursor.
states.totalCount	Int!	Total states for this country.
translations	CountryTranslationCollection!	All country translations.
translations.edges	[Edge!]!	Translation edges with cursors.
translations.edges.node	CountryTranslation!	Individual translation.
translations.edges.node.id	ID!	Translation identifier.
translations.edges.node._id	Int!	Numeric translation ID.
translations.edges.node.countryId	Int!	Associated country ID.
translations.edges.node.locale	String!	Language locale code (e.g., 'en', 'ar', 'fr').
translations.edges.node.name	String!	Country name in locale language.
translations.edges.cursor	String!	Pagination cursor for this translation.
translations.pageInfo	PageInfo!	Pagination information for translations.
translations.totalCount	Int!	Total translations for this country.
pageInfo	PageInfo!	Pagination information.
pageInfo.hasNextPage	Boolean!	More countries available.
pageInfo.hasPreviousPage	Boolean!	Previous countries available.
pageInfo.startCursor	String	First country cursor.
pageInfo.endCursor	String	Last country cursor.
totalCount	Int!	Total countries in system.

Use Cases

1. Address Form

Use the "For Address Form" example to populate country and state dropdowns in checkout forms.

2. Multi-Language Support

Use the "With All Translations" example to display country names in all supported languages.

3. Shipping Configuration

Use the "Basic" example to get all available shipping destinations.

4. Pagination

Use the "With Pagination" example to handle large country lists efficiently.

5. Complete Data

Use the "With States" example to get all country and state information at once.

Best Practices

1. Cache Countries Data - Countries rarely change, cache the entire list
2. Load Countries on App Init - Fetch and store countries when application starts
3. Support State Selection - Always fetch states for proper address forms
4. Use Translations - Fetch translations for all supported languages
5. Optimize Field Selection - Request only fields needed for your use case
6. Pagination for Mobile - Use pagination on mobile to reduce data transfer
7. Sort by Frequency - Display most-used countries first in UI

State Availability

Some countries may have states configured, while others may not:

• Countries with states: US (50+), Canada, India, etc.
• Countries without states: Many smaller countries return empty states collection
• Always check totalCount to determine if states are available

Related Resources

• Get Country - Get single country by code
• Country States - Get states for specific country
• Pagination Guide - Cursor pagination documentation
• Shop API Overview - Overview of Shop API resources