=== Caravel Track for WooCommerce ===
Contributors: caravelsuite
Tags: woocommerce, shipment tracking, order tracking, tracking number, carriers
Requires at least: 6.4
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 1.0.0
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Add tracking numbers to WooCommerce orders, recognise the carrier, and show tracking links in emails, My account and a tracking page.

== Description ==

Caravel Track adds a Tracking box to the WooCommerce order screen. Type or paste the tracking number: the carrier is recognised from the number's format and check digit (and the shipping country), and you can always pick it yourself. The customer then sees a link that opens the carrier's own tracking page.

* **Tracking box on the order**: one or more shipments per order, each with tracking number, carrier, ship date and, optionally, the items and quantities in it. Adding and deleting work without reloading the page, and also by saving the order. A private order note is added for each change.
* **1,006 carriers included**, from national posts to local couriers, each with its tracking page address. Choose your usual carriers so they come first, and add your own (name and tracking address).
* **Carrier recognition** for 916 tracking number formats, with 31 check digit algorithms (UPU S10 postal numbers, UPS, FedEx, USPS, DPD, GLS, Hermes/Evri, Colissimo, Correos, Mondial Relay and more). When a number could belong to several carriers, your carriers and the shipping country decide; if it is still unclear, you are asked to choose.
* **Tracking links for customers**: in the Completed order email by default, and in any other customer email you choose (HTML and plain text); in My account (a Track button in the orders list and a Tracking section on the order); and on a public tracking page.
* **Tracking page**: create it with one click, or use the `[caravel_track]` shortcode or the Order tracking block. Customers enter their order number and billing email. Emails link straight to the result. Only the order status and the shipments are shown, never names, addresses or prices. Attempts are limited per visitor, the error message never reveals whether an order exists, and the page is not cached or indexed.
* **Optional Shipped status** with its own customer email (WooCommerce > Settings > Emails). Shipped orders count as paid in reports and keep download access. When tracking is added you can change the order status to Shipped or Completed.
* **Orders list**: a Tracking column, search by tracking number and a bulk action to change orders to Shipped.
* **CSV import** of tracking numbers (WooCommerce > Tracking import), with a check of every row before anything is saved: order not found, invalid number, duplicate, unknown carrier. Comma, semicolon and tab separators, files saved by Excel and header rows in six languages are recognised. Large files are imported in small batches.
* **CSV export** of the tracking numbers of a date range, safe to open in spreadsheets.
* **Tracking from WooCommerce Shipment Tracking**: tracking saved by other plugins and shipping tools in that format is shown as it is, and can be copied in one click.
* **REST API**: a `caravel_tracking` field on WooCommerce orders (`wc/v3/orders`) and `caravel-track/v1/orders/<id>/shipments` routes to list, add and delete shipments.
* Works with High-Performance Order Storage and with the classic order storage.
* English, Portuguese (Portugal), Spanish, French, German and Italian.
* No external calls, tracking, advertising or remote assets.

= What the plugin does not do =

The plugin does not contact carriers. The tracking link opens the carrier's website in the customer's browser, and the carrier's website shows where the parcel is. Delivery status is not read into WooCommerce, and orders are not updated from the carrier.

= For developers =

* `caravel_track_init` (action, with the `Shipments` and `Carriers` services) runs once the plugin is running.
* `caravel_track_shipment_saved` (action: order, shipment, context) and `caravel_track_shipment_deleted` (action: order, shipment).
* `caravel_track_carriers` (filter) adds, renames or removes carriers; `caravel_track_tracking_url` (filter) changes a tracking link.
* `caravel_track_find_order` (filter) finds the order for a number typed on the tracking page or in a CSV file, for stores with their own order numbers. Numbers stored in the `_order_number` meta are already supported.
* `caravel_track_settings_fields` (filter) and `caravel_track_settings_saved` (action) for WooCommerce > Settings > Tracking.
* `caravel_track_order_box_after` (action) at the end of the order Tracking box, and `caravel_track_tracking_page_after` (action) at the end of a tracking page result and of the My account order view (third argument: `tracking_page` or `my_account`).
* The email template `emails/customer-shipped-order.php` can be overridden in your theme like any WooCommerce email template.

The carrier list in `data/` is generated by `bin/build-carriers.py` in the source repository from the sources listed in THIRD-PARTY-NOTICES.txt.

More at [caravelsuite.com](https://caravelsuite.com/).

== Installation ==

1. Install and activate WooCommerce 8.0 or later on WordPress 6.4 or later with PHP 7.4 or later.
2. Upload caravel-track.zip under Plugins > Add New > Upload Plugin and activate it.
3. Open WooCommerce > Settings > Tracking: choose your carriers, the emails with tracking, and create the tracking page.
4. Open an order, type the tracking number in the Tracking box and click Add tracking.

== Frequently Asked Questions ==

= Does the plugin show where the parcel is? =

No. It stores the tracking number and builds the link to the carrier's tracking page. The customer clicks the link and the carrier's website shows the delivery status. Your store never contacts the carrier.

= My carrier is not in the list. =

Add it in WooCommerce > Settings > Tracking > Other carriers, one per line: the name, a vertical bar and the tracking page address with `{n}` where the tracking number goes. For example: `My Courier | https://example.com/track?number={n}`. Only https addresses are accepted.

= The carrier was recognised wrongly. =

Some formats are used by several carriers. Choose your usual carriers in the settings so they win, or pick the carrier yourself in the Tracking box before adding the number. You can always change it by deleting the tracking number and adding it again.

= Which emails include the tracking? =

The Completed order email and the Shipped order email by default. You can add others, such as Processing order or Customer note, in the settings. The tracking only appears once the order has a tracking number, so add the tracking before changing the status.

= Is the tracking page safe? =

The visitor must give the order number together with the billing email, or follow the link from an email, which contains the order's private key. Only the order status and the shipments are shown. After 10 failed attempts in 15 minutes (5 for the same order number) the visitor has to wait. The page sends no-cache, no-index and no-referrer headers.

= What format does the CSV import need? =

One tracking number per row: order number, tracking number, carrier (optional) and ship date (optional, YYYY-MM-DD or DD/MM/YYYY). With a header row the columns may be in any order. Up to 2 MB and 2,000 rows per file. Without a carrier the plugin tries to recognise it from the number; rows that cannot be matched are listed and skipped.

= What happens to Shipped orders if I turn the status off? =

They keep their status and stay visible until you change them. If you delete the plugin with "Delete data" checked, they are changed to Completed.

= What is deleted when I delete the plugin? =

Nothing, unless "Delete data" is checked in the settings. Then the tracking numbers saved by this plugin, its settings, the tracking page it created and its temporary data are removed. Tracking saved in the WooCommerce Shipment Tracking format is never changed.

= Is personal data sent anywhere? =

No. The plugin makes no external requests. Tracking numbers are stored on the order in your own database. The tracking page stores only hashed counters of attempts for 15 minutes.

== Screenshots ==

1. The Tracking box on the order screen: the carrier is recognised as you type the number.
2. The orders list with the Tracking column.
3. CSV import: every row is checked before anything is saved.
4. WooCommerce > Settings > Tracking.
5. The public tracking page with the order status and the tracking link.
6. The tracking table in the customer email.

== Changelog ==

= 1.0.0 =
* Initial release.

== Upgrade Notice ==

= 1.0.0 =
Initial release.
