Countries

Countries are the catalog of nations available for billing/shipping addresses, taxes, and storefront scoping. Each country may have one or more sub-divisions ("states", "provinces", "territories" — generically called country states in this API).

Endpoints

Method	Path	Purpose
GET	/api/shop/countries	Paginated list of countries
GET	/api/shop/countries/{id}	Single country by ID

Use the example switcher above to flip between the two.

Request Headers

Header	Required	Description
Accept	Yes	application/json
X-STOREFRONT-KEY	Yes	Storefront API key (pk_storefront_…)
X-Locale	No	Override request locale

Query Parameters (collection only)

Parameter	Type	Default	Description
page	integer	1	Page number (1-based)
per_page	integer	10	Items per page. Max 50.

Pagination headers (X-Total-Count, X-Page, X-Per-Page, X-Total-Pages) are emitted on the collection. See Pagination.

Country Object Fields

Both endpoints return the same shape — the collection wraps an array of these objects, the single endpoint returns one.

Field	Type	Description
id	integer	Country primary key
code	string	ISO 3166-1 alpha-2 country code (AF, CA, US, IN, …)
name	string	Default English name
states	array	Inline list of country states for this country. Empty [] for countries with no sub-divisions in Bagisto's data
translations	array	All locale translations as inline objects: { id, countryId, locale, name }. Unlike attributes, channels, and categories, these are full objects rather than path references, so no extra call is needed per locale.

There is no translation field holding just the request locale, as there is on other resources — pick the entry from translations whose locale matches your X-Locale.

Inline states[] shape

Each entry has the same fields as /country-states/{id} — see the Country States page.

Use Cases

• Populate a country dropdown in a checkout / address form.
• Look up a country by ISO code (?code=US) is not supported — fetch the full list and filter client-side, or use the GraphQL query for a single lookup.
• Resolve a country's localized display name from translations[] based on the customer's locale.
• Chain to the country's states for a country/state cascade picker (use the nested states endpoint to skip refetching the country payload).

Best Practices

• Cache the list — there are 254 countries and the set effectively never changes; refetching it on every checkout render wastes a round trip.
• Raise per_page to 50 and page through — the default of 10 means 26 requests to collect the full list.
• Read the states from the country's own states block — it is inline, so a country/state picker needs no second call per country.
• Send X-Locale rather than reading translations — country names already follow the request locale.

Related Resources

• Country States — state and region rows for address forms
• Introduction → IRIs & HATEOAS — how to dereference the path references in these payloads