Zones, Regions & Pincodes

The three building blocks AIR uses to describe "where" — a coarse sales Zone, a fine-grained administrative Region tree, and the postal Pincodes that sit under a region. Warehouses, customer addresses and carrier serviceability all point back to these records.

Permissions

All three resources on this page — Zones, Regions and Pincodes — are restricted to super administrators only. The console checks this with a hardcoded "is this user a super admin?" test, not a permission string, so granting someone the seeded zone.view, region.view or pincode.view permissions on a non-super-admin role has no effect — they still will not see these pages. Only the super_admin role can open Geography today.

How the three fit together

A Zone is a broad grouping used for sales/administrative rollups — think of it as a label you attach to a set of Regions. A Region is the real geographic unit and is organised as a tree: every region (except the top-level country row) has a Parent Region, and the console tracks how deep in the tree a region sits via a computed Depth column. The conventional depth of the tree runs Country → State → District → Sub-District → Town/Village, one region_type per level. A Pincode is a postal code record that belongs to exactly one Region (its region_id) and, in turn, is where carrier serviceability and warehouse/customer addresses are ultimately anchored.

Zones group Regions loosely; Regions form a strict parent/depth tree; Pincodes hang off whichever Region they belong to.

Zones

Zones live under Geography → Zones in the sidebar. A Zone is a flat, non-hierarchical grouping — it has no parent of its own, and any number of Regions can be tagged into it via the Regions tab.

Zone list

Column	Shows
`name`	Zone name. Searchable, sortable.
`code`	Short unique code, shown as a Code badge. Searchable.
`assignedUser.u_id`	Label "Assigned User" — the User ID of the staff member responsible for the zone, if one is set.
`regions_count`	Label "Regions" — count of Regions currently tagged to this zone. Sortable.
`is_active`	Label "Active" — a tick/cross icon.
`created_at`	Date/time created. Sortable; hidden by default — switch it on from the column toggle.

Filter: Active Status (yes/no/either) is the only filter on this list.

Screenshot placeholderThe Zones list — Name, Code badge, Assigned User, Regions count, Active icon columns, with the Active Status filter panel open.

Create / edit a Zone

Select New zone on the list, or Edit on a row. The form is a single section, "Zone Details":

Field	Type	Required	Notes
`code`	Text	Yes	Max 20, unique. Locked (disabled) once the zone exists — you cannot rename the code on edit.
`name`	Text	Yes	Max 100, unique.
`description`	Textarea	No	Full width.
`assigned_user_id`	Select (searchable)	No	Label "Assigned User". Options list every user as `"{u_id} — {full_name}"`. Nullable.
`is_active`	Toggle	No	Defaults on.

Screenshot placeholderThe Zone create/edit form — Code, Name, Description, Assigned User select and the Active toggle.

Deleting a Zone is not guarded

Unlike Regions (below), Delete on a Zone has no safety check at this level — the console will let you delete a zone even if Regions are still tagged to it. Deleting simply removes the zone grouping; the Regions themselves are not deleted, but they lose their zone tag. Double-check the Regions count column before deleting a zone you are not sure is empty.

Regions tab

Open a Zone and switch to its Regions relation manager to see and manage which Regions are tagged into it.

Column	Shows
`name`	Region name, searchable.
`region_type`	Type badge (Country/State/District/SubDistrict/TownVillage) — plain styling, not colour-coded.
`is_active`	Label "Active" — tick/cross icon.

Actions here: header Create (adds a brand-new region, pre-tagged to this zone), row Edit, and row Delete. Unlike the Zone delete you just read about, this Delete is guarded — it reuses the same protective check described in Deleting a Region below, even though you triggered it from inside a Zone's tab.

Regions Built

Regions live under Geography → Regions. This is the console's fullest geography editor: create, edit and delete, plus two relation managers for the region's children and its pincodes.

Region list

Column	Shows
`name`	Region name. Searchable, sortable.
`short_name`	Abbreviated name. Searchable.
`region_type`	Type badge — plain styling (no colour map).
`zone.name`	Label "Zone" — the tagged Zone, if any.
`parent.name`	Label "Parent" — the region one level up the tree.
`depth`	How many levels below the top of the tree this region sits. Sortable. Computed/maintained by the system — never entered by hand.
`is_active`	Label "Active" — tick/cross icon.
`created_at`	Sortable; hidden by default.

Filters:

Filter	Narrows to
Region Type	One of the 5 `RegionType` cases: Country, State, District, Sub-District, Town/Village.
Zone	Regions tagged to a chosen Zone.
Active Status	Yes / No / Either.
Parent Region	All direct children of a chosen parent region — searchable select.

Screenshot placeholderThe Regions list with the Region Type, Zone, Active Status and Parent Region filters open, showing Name, Short Name, Type, Zone, Parent and Depth columns.

Create / edit a Region

The form is organised into four sections. Only "Region Details" is expanded by default — the rest are collapsible and start collapsed.

Region Details

Field	Type	Required	Notes
`name`	Text	Yes	Max 255.
`short_name`	Text	No	Max 100.
`report_name`	Text	No	Max 255 — the name used on printed reports.
`region_type`	Select	Yes	Country / State / District / Sub-District / Town-Village.
`parent_id`	Select (searchable)	No	Label "Parent Region". See the cycle-prevention note just below — nullable (a Country-level region has no parent).
`zone_id`	Select (searchable)	No	Label "Zone". Nullable.
`sub_zone`	Text	No	Max 50, free-text sub-grouping within a zone.
`is_selectable`	Toggle	No	Defaults on.
`is_alias`	Toggle	No	Defaults off — marks the region as an alternate name for another, rather than a real place.
`is_active`	Toggle	No	Defaults on.

You cannot make a region its own ancestor

When you edit an existing region, the Parent Region list is filtered to remove that region's own row and every one of its descendants. This is a deliberate cycle guard — without it you could pick a child of the region as its own parent and corrupt the tree. If a region you expect to see as a possible parent is missing from the list, it is almost certainly because it sits underneath the region you are editing.

Government Codes (collapsible)

Field	Type	Required	Notes
`st_code`	Text	No	Max 10 — state code.
`dt_code`	Text	No	Max 10 — district code.
`sdt_code`	Text	No	Max 10 — sub-district code.
`tv_code`	Text	No	Max 10 — town/village code.
`gst_st_code`	Number	No	GST state code, numeric form.
`gst_st_code_char`	Text	No	Max 10 — GST state code, character form.

Assignments (collapsible)

Field	Type	Required	Notes
`region_account_holder_id`	Select (searchable)	No	Label "Account Holder". Nullable.
`region_user_id`	Select (searchable)	No	Label "Region User" — the staff member responsible for this region. Nullable.

Sort Orders (collapsible, 3 columns)

Field	Type	Required	Notes
`sort_order_1`	Number	No	Nullable — custom display ordering, use 1–3 as your reporting needs demand.
`sort_order_2`	Number	No	Nullable.
`sort_order_3`	Number	No	Nullable.

Depth and path are not form fields

The depth column you see on the list, and the underlying materialized_path the system uses for fast tree lookups, are never typed in by hand. They are derived automatically from where you place the region in the tree via Parent Region, and kept in sync by the system whenever a region moves.

Screenshot placeholderThe Region create/edit form with Region Details expanded and Government Codes, Assignments and Sort Orders shown collapsed.

Deleting a Region

Select Delete on a region row, or the header Delete action on a region's edit page. Before anything is removed, the console runs a protective check and will refuse to delete a region that is still in use:

Delete is blocked, with a red notification, when…

…the region still has one or more active child regions underneath it in the tree, or the region is referenced by any geography scope (a user's assigned area of responsibility). In either case the delete is halted before it happens and you see a red "cannot delete" notification explaining why. To proceed, first re-parent or deactivate the region's children, and remove any geography scopes pointing at it — then delete will succeed.

This same guard is reused in two other places, so the rule is consistent everywhere you can delete a region: the Delete action inside a Region's own Children tab, and the Delete action inside a Zone's Regions tab.

Children tab

Open a Region and switch to Children to see every region one level directly beneath it.

Column	Shows
`name`	Child region name, searchable.
`region_type`	Type badge.
`is_active`	Label "Active" — tick/cross icon.

Header Create adds a new child directly under this region (name, type and active toggle only — the parent is set automatically). Row Edit and Delete are available; Delete uses the same guard described above.

Pincodes tab

Open a Region and switch to Pincodes to see every pincode filed under it.

Column	Shows
`pincode`	The postal code, searchable.
`office_name`	Post office name.
`state_name`	State name as recorded on the pincode record.
`is_active`	Label "Active" — tick/cross icon.

Header Create opens a short form (pincode, office name, state name, district name, active toggle) that files a new pincode straight under this region. Row Edit and Delete are plain — unlike the region-delete guard above, deleting a pincode here is not blocked by any check.

Screenshot placeholderA Region's edit page with the Children and Pincodes tabs visible below the form, each showing its own mini-table and Create button.

Pincodes Built

Pincodes also have their own full page at Geography → Pincodes — the same records you can reach from a Region's Pincodes tab, but listing every pincode in the system regardless of which region it sits under, with its own filters.

Pincode list

Column	Shows
`pincode`	The postal code. Searchable, sortable.
`office_name`	Post office name. Searchable.
`office_type`	Free-text office type (plain text, not a badge).
`state_name`	State name as recorded on the pincode.
`district_name`	District name as recorded on the pincode.
`region.name`	Label "Region" — the region this pincode is filed under.
`is_active`	Label "Active" — tick/cross icon.
`created_at`	Sortable; hidden by default.

Filters: Active Status (yes/no/either) and Region (searchable select over every region).

Screenshot placeholderThe Pincodes list with the Region filter open, showing Pincode, Office Name, State, District, Region and Active columns.

Create / edit a Pincode

The form has four sections; "Pincode Details" and "System Links" are expanded, "Location" and "Contact" are collapsible.

Pincode Details

Field	Type	Required	Notes
`pincode`	Text	Yes	Max 10, unique.
`office_name`	Text	No	Max 255.
`office_type`	Text	No	Max 50, e.g. "Sub Office".
`delivery_status`	Text	No	Max 50.

Location (collapsible)

Field	Type	Required	Notes
`state_name`, `district_name`, `taluka`, `division_name`	Text	No	Max 150 each — free-text location descriptors, not linked to the Region tree.
`region_name`	Text	No	Label "India Post Region" — max 150. Not the same thing as the `region_id` link below; this is India Post's own regional label.
`circle_name`, `head_office`, `sub_office`	Text	No	Max 255 each — India Post administrative hierarchy names.

Contact (collapsible, starts collapsed)

Field	Type	Required	Notes
`telephone`	Text	No	Max 50.
`general_notes`	Textarea	No	Full width.

System Links

Field	Type	Required	Notes
`region_id`	Select (searchable)	No	Label "Region" — the actual AIR Region this pincode is filed under (the link used by the Region's Pincodes tab). Nullable.
`ivr_dial_to_user_id`	Select (searchable)	No	Label "IVR Dial To User" — which staff member's phone an inbound IVR call from this pincode's area should ring. Nullable.
`is_active`	Toggle	No	Defaults on.

Screenshot placeholderThe Pincode create/edit form showing Pincode Details and System Links expanded, Location and Contact collapsed.

Carrier Serviceability tab

Open a Pincode and switch to its relation manager to record which delivery carriers can serve this pincode.

Column	Shows
`carrier_code`	Searchable — the carrier's code.
`is_serviceable`	Label "Serviceable" — tick/cross icon.
`is_metro`	Label "Metro" — tick/cross icon, flags a metro-rate pincode.
`zone`	Free-text carrier zone code for this pincode.

Header Create opens a form: carrier_code (required, max 50), is_serviceable (toggle, defaults off), is_metro (toggle, defaults off), zone (text, max 5). Row Edit and Delete are plain, with no guard.

Bulk pincode import — Planned

A permission named pincode.import ("Bulk import pincode data") exists, and it is tempting to assume there is a spreadsheet-upload screen somewhere. There is not. No import button, file-upload dialog, or bulk-import service is wired into the console today. Every pincode — India has tens of thousands of them — must currently be entered one at a time through the create form described above, either from Geography → Pincodes directly or from a Region's Pincodes tab. Treat any workflow that assumes a bulk upload exists as aspirational until this is built.

Where else these records are used

Regions and Pincodes are not self-contained — other modules point at them:

A Warehouse can be linked to a Region and a Pincode directly on its own form, and separately to a whole set of Regions it serves via its Regions tab.
Customer addresses reference both a Pincode and a Region.
A user's geography scope — which part of the country they are allowed to work in — is expressed as a Region reference. Deleting a Region that still backs a scope is exactly the case the delete guard above exists to catch.

See also Warehouses & Carriers for how Regions attach to a Warehouse's serviceable area, and Schedulers for the background jobs that read warehouse/region data every day.