=== Celery Shipping – Ciudades de Colombia y Envíos Personalizados ===
Contributors: celerysoftware
Tags: colombia, envíos colombia, ciudades de colombia, departamentos, municipios
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.4.3
License: GPLv3
License URI: https://www.gnu.org/licenses/gpl-3.0.html

Colombian departments and DANE municipalities at checkout, plus per-city shipping rates with an included weight and a per-kilo surcharge.

== Description ==

Celery Shipping adapts WooCommerce to the Colombian market and solves, through configuration fields and without writing any code, the most common shipping rule in the country: **a base cost that covers a certain weight, plus a surcharge for every kilo above it**.

For example: *10,000 COP up to 20 kg, plus 500 COP for each additional kilo, for a selected group of cities.*

The plugin ships **two independent modules** that can be switched on or off separately, so you can use only the part you need.

= Localization module (can be enabled or disabled) =

Registers Colombia's 32 departments plus Bogota D.C. as WooCommerce states, using official ISO codes. It loads the 1,104 municipalities published by DANE (DIVIPOLA) and turns the checkout "City" field into a dependent dropdown: the customer picks a department and only its municipalities are listed.

* Renames the checkout labels for the Colombian context: the state field becomes **Departamento**.
* The city becomes **required** and is picked from a controlled list instead of typed by hand.
* The postcode is left **optional**.
* This module **works on its own** and is compatible with any other shipping plugin.

= City Shipping module (can be enabled or disabled) =

Adds its own shipping method, **"Celery — Envio por Ciudad"**, which is placed inside a shipping zone and configured through fields. Its fields are:

* Title shown at checkout
* Base cost
* Weight included in that base cost
* Price per additional kilo
* List of cities where the rate applies
* Maximum weight
* Tax status

The rate is **only offered when the customer's destination city is in the selected list**. The calculation charges the base cost up to the included weight, and above that it adds the price per additional kilo for every extra kilo, rounded up.

The **maximum weight** works as an optional hard cap: if the order exceeds it, the rate disappears. This is useful to force a manual quote on large orders.

= The city picker =

Picking from 1,104 municipalities with a plain list is unworkable, so the picker is a searchable checkbox list **grouped by department**, with collapsible sections:

* Every department has a checkbox to select or deselect **all** of its cities at once.
* A counter of selected cities per department, and a total counter.
* The search **filters live** and expands only the departments that match.

Each city is identified internally by **department + city**. Because of that, municipalities that share a name across departments — Rionegro in Antioquia and Rionegro in Santander, for example — are independent entries, and you can configure them separately with different prices in different methods.

= Automatic migration =

When updating from earlier versions, the cities already saved are converted to the new format across every method in every zone, so nothing has to be selected again. It runs only once.

= Settings page =

A **"Celery Shipping"** tab under WooCommerce → Settings, with the switches to turn each module on or off independently.

= Compatibility and data =

The plugin declares compatibility with **HPOS** (High-Performance Order Storage) and with the block-based checkout. It is designed for the **classic checkout**.

Department and municipality data comes from the Political-Administrative Division (DIVIPOLA) published by **DANE**, public information of the Colombian government.

== Installation ==

1. Install and activate the plugin. It requires WooCommerce to be active.
2. Go to **WooCommerce → Settings → Celery Shipping** and check that the modules you want are switched on. Both are on by default.
3. If you are going to use the shipping module, go to **WooCommerce → Settings → Shipping** and open a shipping zone.
4. Click **Add shipping method** and choose **Celery — Envio por Ciudad**.
5. Edit the method and fill in the fields: title, base cost, included weight, price per additional kilo, and the cities where it applies.
6. Save.

= Example: 10,000 COP up to 20 kg, +500 COP per additional kilo =

In the shipping method, set:

* **Base cost:** 10000
* **Included weight:** 20
* **Price per additional kilo:** 500
* **Cities:** tick the ones that apply
* **Maximum weight:** 0 for no limit

An order of 23.2 kg to one of those cities is charged 10,000 + (4 × 500) = 12,000, because the extra 3.2 kg are rounded up to 4.

== Frequently Asked Questions ==

= Can I use only the departments and municipalities, with another shipping plugin? =

Yes. Turn the City Shipping module off in the settings tab and leave the Localization module on. The dependent checkout dropdown keeps working alongside any other shipping plugin.

= And the other way around, only the shipping method? =

That works too. Turn the Localization module off. Keep in mind that without it the customer types the city by hand, and it may not match exactly the cities you selected in the method.

= How do I handle two cities with the same name in different departments? =

They are handled automatically. Each city is identified by department + city, so Rionegro (Antioquia) and Rionegro (Santander) are separate entries in the picker and can go into different methods with different prices.

= What if I need several rates for the same group of cities? =

Add several "Celery — Envio por Ciudad" methods to the same zone, each with its own cost and maximum weight. WooCommerce will show the ones that apply to the order.

= Does it work with the block-based checkout? =

The plugin declares compatibility with the block checkout and with HPOS, but it is designed and tested for the **classic** (shortcode) checkout.

= A municipality is missing. What do I do? =

The data comes from DANE's DIVIPOLA. If you find a municipality that is missing or misspelled, report it on the plugin support forum and mention the department.

== Screenshots ==

1. Checkout with dependent Department and City / Municipality dropdowns, filled with official DANE data.
2. Both modules can be switched on or off independently, so you can use only the part you need.
3. Shipping rate: base cost, the weight it already covers, and the surcharge for every extra kilo.
4. Pick exactly which cities a rate applies to, grouped by department.
5. The municipalities of a department, straight from the DANE list.

== Changelog ==

= 1.4.3 =
* Renamed the plugin to "Celery Shipping – Ciudades de Colombia y Envíos Personalizados".
* The readme is now written in English, as required for the WordPress.org Plugin Directory.
* The notice shown when WooCommerce is missing is now a warning instead of an error, and is translatable. WooCommerce is not broken by its absence: the plugin simply does not start.
* Compatibility declared up to WordPress 7.1 and WooCommerce 11.1.
* The plugin header description is now in English as well.
* No changes to shipping calculation, the city picker, the migration or the DANE data.

= 1.4.1 =
* Automatic one-time migration: cities saved in the previous format (city name only) are converted to the new department + city format on update, across every method in every zone, so nothing has to be selected again. Cities with the same name in several departments are expanded to all their variants, matching the previous behaviour.

= 1.4.0 =
* The city picker is now grouped by department: collapsible sections, each with a checkbox to select or deselect the whole department, plus per-department and total counters. Live search expands the matching groups and hides the rest.

= 1.3.0 =
* Cities are identified by department + city, so municipalities that share a name across departments (for example Rionegro in Antioquia and in Santander) are independent entries and can go into different methods with different prices.
* The rate is matched against the checkout's department and city. Note: existing selections must be selected again after updating, because the internal format changed. A fallback keeps old selections working until they are saved again.

= 1.2.1 =
* Fixed: cities sharing a name across departments were collapsed, so only one of them appeared in the picker.

= 1.2.0 =
* New modular architecture. A "Celery Shipping" tab under WooCommerce → Settings lets you turn each module on or off independently.
* The Localization module (departments, municipalities and the dependent checkout selector) can now run on its own, compatible with any other shipping plugin.
* The City Shipping module is optional and can be turned off when another shipping plugin is used.

= 1.1.0 =
* The base cost now includes a configurable weight, with a per-extra-kilo surcharge (rounded up) above that weight.
* The city selector became a searchable checkbox picker, with a selected counter and a clear-all control.
* Maximum weight is now an optional hard cap that hides the rate when exceeded, independent from the surcharge.

= 1.0.0 =
* Initial release. DANE departments and municipalities, dependent dropdown on the classic checkout, and per-city shipping method with a weight limit.
