data-src=../../../includes/saas-only.md

Custom regions

The /V1/directory/countries/:countryId/regions REST endpoints allow you to create and manage custom regions, such as states or provinces, for countries in which this data is not predefined in Adobe Commerce.

Each custom region receives a region_id, so you can use it in customer addresses, checkout, shipping, and tax rules.

These endpoints are designed for:

• Administrators who sell in countries that are missing state or province data
• Third-party integrations that load region lists from external systems, such as ERP and address-validation services
• Automated workflows that create every region for a country in a single request

data-variant=info

data-slots=text

Authentication

All endpoints require an admin or integration bearer token. The token must belong to a role that includes the Manage Country Regions (Magento_DirectoryRegionRestApi::country_region) permission.

System and custom regions

The system field in each response indicates if this is a system region or a custom region.

The following rules apply to all regions:

• Region codes must be unique (case-insensitive) within each country.
• Regions are global. They are not scoped to a website or store view.
• When the store locale matches an entry in locale_names, Commerce displays that name. Otherwise, it displays default_name.

REST API reference

The API exposes the following operations, which are all secured by the Magento_DirectoryRegionRestApi::country_region permission resource:

Path parameters

Field reference

The create and update endpoints accept the following fields for each region.

data-variant=info

data-slots=text

Each response returns region objects with the following fields.

List regions for a country

Returns the system and custom regions for the country in the path. The results are always limited to that country, in addition to any search criteria you pass.

There is no endpoint that retrieves a single region by ID. Filter on region_id instead. The following example returns the region with the code 25 for the Dominican Republic:

GET /V1/directory/countries/DO/regions
    ?searchCriteria[filter_groups][0][filters][0][field]=code
    &searchCriteria[filter_groups][0][filters][0][value]=25
    &searchCriteria[filter_groups][0][filters][0][condition_type]=eq

Response (200):

{
  "items": [
    {
      "region_id": 1187,
      "country_id": "DO",
      "code": "25",
      "default_name": "Santiago",
      "locale_names": [],
      "system": false
    }
  ],
  "search_criteria": {
    "filter_groups": [
      {
        "filters": [
          {
            "field": "code",
            "value": "25",
            "condition_type": "eq"
          }
        ]
      }
    ]
  },
  "total_count": 1
}

Create custom regions

Creates one or more custom regions for the country in the path. A request can contain 1 to 500 regions.

If any region fails validation, no regions are created.

Request body:

{
  "regions": [
    {
      "code": "01",
      "default_name": "Distrito Nacional",
      "locale_names": [
        {
          "locale": "en_US",
          "name": "National District"
        }
      ]
    },
    {
      "code": "25",
      "default_name": "Santiago"
    },
    {
      "code": "32",
      "default_name": "Santo Domingo"
    }
  ]
}

Response (200):

Returns the created regions in the same order as the request.

[
  {
    "region_id": 1186,
    "country_id": "DO",
    "code": "01",
    "default_name": "Distrito Nacional",
    "locale_names": [
      {
        "locale": "en_US",
        "name": "National District"
      }
    ],
    "system": false
  },
  {
    "region_id": 1187,
    "country_id": "DO",
    "code": "25",
    "default_name": "Santiago",
    "locale_names": [],
    "system": false
  },
  {
    "region_id": 1188,
    "country_id": "DO",
    "code": "32",
    "default_name": "Santo Domingo",
    "locale_names": [],
    "system": false
  }
]

Update a custom region

Updates the code, default name, and locale-specific names of a custom region.

The request requires both code and default_name.

data-variant=warning

data-slots=text

Request body:

{
  "region": {
    "code": "25",
    "default_name": "Santiago de los Caballeros",
    "locale_names": [
      {
        "locale": "en_US",
        "name": "Santiago"
      }
    ]
  }
}

Response (200):

{
  "region_id": 1187,
  "country_id": "DO",
  "code": "25",
  "default_name": "Santiago de los Caballeros",
  "locale_names": [
    {
      "locale": "en_US",
      "name": "Santiago"
    }
  ],
  "system": false
}

Delete a custom region

Deletes a custom region and its locale-specific names.

Response (200):

true

Error handling

The API returns standard HTTP status codes: