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
Attribute/Channel/Category,translationson Country is returned as inline objects (not IRI strings). This avoids an extra round-trip per locale. There is notranslationfield for the request locale — pick the entry that matches yourX-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).