Instructions for Import cities

What the add-on does

The add-on introduces a dedicated city import workflow in CS-Cart. A CSV file can create new cities and update existing ones with a city name, country, state or region code, universal postal code, and description language.

The add-on works with the directory provided by the standard Cities add-on. It has no separate settings page, background task, or schedule: imports are started manually in the standard CS-Cart form, and a universal index can also be entered in a city record.

Before importing

1. Back up the database, especially before adding or updating cities in bulk.
2. Prepare a test file with one or several rows and check the result before processing the full file.
3. Make sure that the standard Cities add-on is active and that the user has the catalog management permission.
4. When updating existing cities, include their city_id values in the file. Do not update a large directory by city names alone.

Important: if city_id is omitted, the add-on looks for an existing record only by the exact city name and uses the match it finds. Country, state or region, and language are not considered during this lookup. Use city_id for cities with the same name and for all bulk updates; otherwise, the wrong record may be changed.

Where to find the add-on

The import form is available in the administration panel at Administration → Import data → MS: Import cities.

The Universal index field appears in the city creation and editing form provided by the standard Cities add-on. The exact menu location of the city directory depends on the CS-Cart version and edition.

The import section is available to users with the catalog management permission. There are no separate settings in the add-on record.

Import file fields

The names below correspond to the import schema fields. If your CSV headers are different, map them to the appropriate fields in the standard CS-Cart import form.

How to prepare the data

For a new city: leave city_id empty and provide a unique city name, the exact name of an existing country, a state or region code, and optionally a postal code and language.

For an existing city: provide its city_id and fill in the required city, country, and state_code fields. Do not rely on name matching when the directory may contain cities with the same name.

Check state and region codes before importing. If the country and state_code combination does not exist, the add-on creates an active state or region automatically. Its code is used as the initial name in every installed language.

How to import cities

1. Go to Administration → Import data → MS: Import cities.
2. Upload a CSV file with column headers.
3. In the language option, select the language or languages of the imported city descriptions.
4. Map the file columns to the import schema fields. Make sure that city, country, and state_code are present and mapped.
5. For updates, check the city_id column mapping separately.
6. Run the import for the test rows first and review the standard CS-Cart result notification.
7. After checking the test cities, import the full file.

What happens during import

• The value in country is matched to a country in the CS-Cart directory and converted to its internal country code.
• If city_id is provided, it is used as the key of an existing city.
• If city_id is omitted, the add-on searches by the exact city name and creates a new record when no match is found.
• The state or region code is checked within the selected country. A missing state or region is created automatically with an active status.
• The city name is saved for the selected language, and zipcode is saved as the city's universal postal code.

Universal index in a city record

During import, the mapped zipcode value is saved as the city's universal index. The add-on also adds a separate Universal index field to a city record: a non-empty value is saved for the city, while leaving the field empty does not remove an existing value.

The saved index is not prefilled when the city record is opened again: the field is always displayed as empty. Therefore, an empty field alone does not mean that the index was not saved.

How to check the result

1. Create a test CSV file with a unique city name, an existing country, an existing state or region code, a language, and a clearly recognizable test postal code.
2. Import one row and make sure that the operation finishes without errors.
3. Find the city in the standard directory and check its name, country, and state or region.
4. Import the same record again with its city_id and a changed name or postal code. No duplicate city should appear.
5. If the production file uses a new state or region code, review the automatically created record separately and replace its code-based name with a readable name.
6. To confirm that the index was saved, check it in the store workflow or integration that uses the city index. A reopened city record is not suitable for this check because the field is not populated with the saved value.

Troubleshooting

The country is not recognized. Check the spelling. The value must exactly match one of the country names in the CS-Cart directory in an installed language.

The wrong city was updated or a duplicate appeared. Use city_id. Lookup without an identifier uses only the exact city name and ignores the country and state or region.

The state or region is displayed as a code. This is an automatically created record. Open the state or region directory and assign a readable name.

An unexpected state or region appeared after import. Check state_code in the source file. If the code and country combination is not found, the add-on creates a new active record, so a typo in the code produces a separate state or region.

The import reports missing required fields. Check the mapping and values of city, country, and state_code in every row.

The city name was saved in the wrong language. Check the language selected in the import options and the Language column values when that column is used.

The import section is unavailable. Check the standard Cities add-on and the user's catalog management permission.

The saved postal code is not shown in the city form. This is a limitation of the add-on form: it accepts a new non-empty value but does not display the previously saved value.