Countries — Reference
The Countries surface is the geographic master list for an SGEN site. It owns the catalog of country records — ISO codes, display names, default tax and shipping zone bindings, address-format templates, and the per-country checkout-enabled flag. Anything that asks a customer for an address, applies a tax zone, or calculates shipping traces back to a record managed here.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping a localization model. Customer-facing how-tos live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Countries lives under the Settings module in SG-Admin, in the localization group. The module renders three primary views — the country list, the country detail / edit form, and the per-country checkout configuration drawer — and exposes a small set of write operations for enable, disable, edit default bindings, edit address-format template, and bulk import or refresh against an external ISO source.
The module is paired by convention: one half renders the views and prepares the catalog data, the other half handles writes and returns AJAX responses. Engineers reading the SG-Admin source will see this split across two controller files; the reference below describes the combined surface as it appears to a calling integration.
Countries is a master-data surface. The catalog ships seeded with the full ISO 3166-1 set. Operators rarely add rows — the common write operations are toggling checkout-enabled and adjusting default bindings (tax zone, shipping zone, address template) per country. New country records appear only when ISO publishes a change, at which point the bulk refresh action reconciles the catalog against the upstream list.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Settings → Localization → Countries
- URL prefix:
/sg-admin/countries/ - View templates:
application/views/Admin/Settings/Countries/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings → Localization → Countries [ Refresh ISO ] │├──────────────────────────────────────────────────────────────────────┤│ ISO-2 ISO-3 Name Tax zone Shipping Checkout ││ ───── ───── ────────────────── ─────────── ──────── ──────────││ PH PHL Philippines PH-VAT PH-Local ✔ enabled ││ US USA United States US-Sales US-Cont ✔ enabled ││ GB GBR United Kingdom GB-VAT UK-Mail ✔ enabled ││ AU AUS Australia AU-GST AU-Std ✔ enabled ││ IN IND India IN-GST IN-Std — paused ││ ││ Enabled: 47 · Paused: 198 · ISO catalog: 245 ││ [ Edit ] [ Toggle checkout ] [ Address template ] │└──────────────────────────────────────────────────────────────────────┘Actions
The Countries surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List and filter
Returns the country catalog paginated, with ISO-2 code, ISO-3 code, display name, default tax-zone binding, default shipping-zone binding, address-format template name, and checkout-enabled flag. Supports filter by enabled flag, by tax-zone binding, by shipping-zone binding, and by free-text on name. Sort by name, by ISO code, or by region (when region grouping is applied).
View country
Returns the full record for a single country — ISO codes, display name, calling code, default tax-zone binding, default shipping-zone binding, address-format template, currency hint (for currency-locale defaulting), region grouping, and the checkout-enabled flag. Read-only fields (ISO codes, region grouping) are surfaced as locked in the form.
Edit country bindings
Loads the country record into the bindings form. Editable fields cover default tax-zone binding, default shipping-zone binding, address-format template selection, currency hint, and the checkout-enabled flag. ISO codes and display name are read-only — they are sourced from the upstream ISO catalog and updated only via the refresh action.
Enable or disable checkout per country
Dedicated toggle that flips the checkout-enabled flag. A disabled country still appears in admin views (so historical orders remain attributable) but is excluded from the country selector on the storefront checkout. Disabling a country with in-flight carts does not retroactively clear those carts — the disable applies to new cart starts only.
Edit address-format template
Opens the address-template selector for the country. Each template defines the field order, the required-field set, and the postal-code validation pattern presented on the storefront address form. Templates are shared across countries; one template (for example, "US-style") binds to many countries.
Bulk refresh against ISO catalog
Compares the local catalog against the upstream ISO 3166-1 reference. Adds rows for countries the upstream list has added (rare). Marks rows whose display name has changed in the upstream list. Does not delete rows — historical orders may reference codes the upstream list later removed, so removal is operator-confirmed only.
Bulk toggle by region
Convenience operation. Enables or disables checkout for every country in a named region in one call. Used during commerce-feature rollouts to enable a region as a unit rather than country by country.
Engineering note. The bulk operations write per-row, not as a transaction. A partial failure leaves some rows updated and reports the failed subset; resume by filtering on the failed-flag and re-running.
Data model
A country record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
iso_2 | string | Two-letter ISO 3166-1 alpha-2 code. Unique. Read-only. |
iso_3 | string | Three-letter ISO 3166-1 alpha-3 code. Unique. Read-only. |
name | string | Display name. Sourced from upstream ISO catalog. |
region | enum | Region grouping (Africa, Americas, Asia, Europe, Oceania). |
calling_code | string | International dialing prefix (no leading plus). |
tax_zone_id | integer | Default tax-zone binding. Foreign key into Tax Zones. |
shipping_zone_id | integer | Default shipping-zone binding. Foreign key into Shipping Zones. |
address_template_id | integer | Address-format template. Foreign key into Address Templates. |
currency_hint | string | ISO 4217 currency code suggested for this country. Storefront default; customer can override. |
checkout_enabled | boolean | Whether the country appears in the storefront country selector. |
created_at | timestamp | Set on row insert (catalog seed or ISO refresh). |
updated_at | timestamp | Touched on any edit. |
Historical-attribution rule: order records carry the country code at the time the order was placed. Disabling a country here never rewrites that historical attribution.
COUNTRY RECORD├── id integer primary key├── ISO codes iso_2, iso_3 — read-only, upstream-sourced├── identity name, region, calling_code — read-only├── bindings tax_zone_id, shipping_zone_id, address_template_id├── locale hint currency_hint (ISO 4217)├── flag checkout_enabled (boolean)└── timestamps created_at, updated_at↓ referenced by┌─────────────────────────────┐│ Orders (historical record) ││ Customer addresses ││ Tax / shipping calculation │└─────────────────────────────┘Permissions
Access to the Countries surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Countries surface.
Layer 2 — per-action capability. Within SG-Admin, each Countries action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List countries | ✔ | ✔ | ✔ |
| View country detail | ✔ | ✔ | ✔ |
| Edit country bindings | ✔ | ✔ | — |
| Toggle checkout per country | ✔ | ✔ | — |
| Edit address-format template | ✔ | — | — |
| Bulk refresh against ISO | ✔ | — | — |
| Bulk toggle by region | ✔ | — | — |
| Confirm row removal after ISO refresh | ✔ | — | — |
Self-protection rules. The catalog cannot drop to zero enabled countries — at least one country must remain enabled for the storefront checkout to render. The surface returns a structured rejection on the disable that would leave none enabled. ISO codes cannot be hand-edited — they are reconciled only by the bulk refresh action.
Audit. Every write — edit bindings, toggle checkout, edit address template, bulk refresh, bulk toggle, row confirmation — emits an Activity Log entry. The log records the acting operator, the country identifier, and the change shape (field-level diff for edits).
REQUEST│▼┌───────────────────────────┐│ Admin gate │ unauth → reject│ (every /sg-admin/* call) │└─────────────┬─────────────┘│ authed▼┌───────────────────────────┐│ Capability check │ role lacks cap → reject│ (per-action) │ (custom roles override defaults)└─────────────┬─────────────┘│ allowed▼┌───────────────────────────┐│ Self-protection rules │ zero-enabled / hand-edit ISO →│ │ reject└─────────────┬─────────────┘│ passes▼action executes│▼Activity Log entryRelated references
- Currencies — Reference. Each country carries a
currency_hintthat defaults the storefront currency for visitors. Changes to the currency catalog reshape the hint options. - Languages — Reference. Locale registration uses country codes to compose locale identifiers (
en-PH,en-US). The country catalog supplies the country half of every locale tuple. - Tax Zones — Reference. The default tax-zone binding column points here. Tax math runs against the bound zone at checkout.
- Shipping Zones — Reference. The default shipping-zone binding column points here. Shipping math runs against the bound zone at checkout.
- Address Templates — Reference. The address-format template binding points here. The storefront address form renders the bound template per selected country.
- Orders — Reference. Order records carry the country code at the time the order was placed. Historical orders survive country disable.
- Settings — Reference. Owns the address-template catalog, the ISO-refresh schedule, and the region grouping definitions. Changes there reshape the Countries surface defaults.
/docs/countries.