=== TrackKaro Pakistan - Courier Tracking & COD ===
Contributors: usmanghazanfar
Tags: woocommerce, courier tracking, pakistan, cod, postex, bridge courier
Requires at least: 5.8
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.0.115
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Auto-sync WooCommerce orders with PostEx, Leopards, TCS, CallCourier, Sonic, DEX, Daewoo FastEx & Bridge Courier. Real-time courier tracking for Pakistani stores.

== Description ==

TrackKaro keeps your WooCommerce orders in step with the courier, automatically.

Add a tracking number to an order - or book the shipment straight from the order screen - and TrackKaro takes it from there. It checks the courier for you, updates the order status, shows your customer where their parcel is, and marks the order complete when it is delivered. No more opening nine courier websites a day.

**Supported couriers:** PostEx, TCS, Leopards, Sonic / Trax, M&P, Daewoo FastEx, InstaWorld, Nexus Global, Bridge, CallCourier, and DEX (Daraz Express, tracking only).

= How it works =

This plugin is a connector. The work - talking to each courier's API, retrying when one is down, and turning nine different status vocabularies into one - happens on the TrackKaro platform (https://trackkaro.pk), a hosted service run by DANGO Solutions. Your store never calls a courier directly, so nothing slows down and there is nothing for you to maintain.

A TrackKaro account is required. **Signing up is free and stays free** - the Free plan includes 100 parcels a month, every month, with no card and no expiry. Paid plans start where that runs out.

= What you get =

**Statuses that update themselves.** In Transit, Out for Delivery, Delivered - written onto the order in the background, no refreshing.

**A tracking page on your own domain.** Your store name, your colours, the full delivery timeline. Created for you when you activate the plugin; the link goes in your order emails.

**Book shipments without leaving WooCommerce.** Fill in the parcel details on the order screen and the booking reference comes back onto the order. COD, prepaid and zero-value orders all work.

**Book a whole batch at once**, then print a dispatch manifest - a rider handover sheet with a scannable barcode for every parcel and a signature box, split into one sheet per courier. This is the only handover proof that exists on couriers that issue no load sheet of their own.

**Print airway bills and shipping labels**, including the official TCS 3-copy A4 slip. Generated on your own site: no internet needed to print, and no tracking number leaves your store.

**Insights** - your own delivery analytics, worked out from your own orders on your own site, once a month. Which courier actually delivers for you and how fast, which one performs best in each city, which parcels are running longer than usual, and what returns are costing you. Export any of it as CSV. It never asks TrackKaro's servers for anything.

**Payments received.** Upload the payment statement your courier gives you and TrackKaro checks it against what each parcel should have collected, and shows anything that does not add up. Your statement is read once and never saved.

**Auto-complete on delivery**, a live status column in the orders list, a dashboard widget, bulk CSV import of tracking numbers, and optional customer email updates at each milestone.

**Fully HPOS compatible** (High-Performance Order Storage), tested on WooCommerce 5.0 through 9.x.

= Getting started =

1. Install and activate the plugin.
2. Create a free account at [trackkaro.pk](https://trackkaro.pk) - it takes about two minutes.
3. Copy your API token from the TrackKaro dashboard into **TrackKaro -> Settings**.
4. Add a tracking number to any order, or book a shipment from the order screen.

= Pricing =

The Free plan gives you 100 parcels a month, permanently. Paid plans are priced in PKR by monthly parcel volume, and come two ways: **prepaid**, where you pay up front for an allowance, or **postpaid**, where you are billed at the end of the month and never stop mid-dispatch. No contracts. Current plans are at [trackkaro.pk](https://trackkaro.pk).

== Installation ==

1. In your WordPress dashboard go to **Plugins → Add New → Upload Plugin**.
2. Upload the `trackkar-woo.zip` file and click **Install Now**.
3. Activate the plugin.
4. Go to **TrackKaro → Settings** in the WordPress admin menu.
5. Paste your API token from your [TrackKaro dashboard](https://trackkaro.pk/panel).
6. Click **Save Settings**. The plugin will verify your token and confirm the connection.
7. Open any WooCommerce order and add a tracking number — TrackKaro will start syncing within the next cron cycle (typically within 5 minutes).

**First time?** Create your free account at [trackkaro.pk](https://trackkaro.pk) before step 4.

== Frequently Asked Questions ==

= Does this plugin work without a TrackKaro account? =

No. TrackKaro is a hosted service - the plugin is the bridge between your WooCommerce store and the TrackKaro server, which handles all courier API connections, status normalisation, and background polling. You need a TrackKaro account, but creating one is free.

= Do I have to pay? =

Not to start, and not on low volume. The Free plan includes 100 parcels a month, every month - it does not expire and needs no card. If you ship more than that, paid plans are priced in PKR by volume, prepaid or postpaid.

= Which couriers are supported? =

PostEx, TCS, Leopards, Sonic/Trax, M&P, Daewoo FastEx, InstaWorld, Nexus Global, Bridge, CallCourier, and DEX (Daraz Express, tracking only). More are added on demand - contact support if yours is missing.

= Do I need to add my own courier API credentials? =

Not necessarily. TrackKaro maintains central API credentials for most couriers, which your store can use out of the box. If you have your own API keys (e.g. a dedicated PostEx or Leopards account), you can add them in your TrackKaro dashboard for direct access.

= Will this slow down my store? =

No. The plugin loads only on admin pages and offloads all tracking work to WP-Cron background jobs. There is zero impact on your storefront or checkout speed.

= What is the branded tracking page? =

When a customer clicks the tracking link in their order email, they land on a page on your own domain (e.g. `yourstore.com/track-your-order/`) that shows the full delivery timeline in your store's branding. TrackKaro automatically creates this page on plugin activation.

= Can I create courier bookings through the plugin? =

Yes, on every courier that offers a booking API - PostEx, TCS, Leopards, Sonic/Trax, M&P, Daewoo FastEx, InstaWorld, Nexus Global and Bridge. Open the order, fill in the parcel details and submit; the booking reference is saved onto the order. You can also book a batch of orders in one go from the orders list.

= Is it compatible with HPOS (High-Performance Order Storage)? =

Yes. TrackKaro is fully compatible with WooCommerce's High-Performance Order Storage (custom order tables) and has been tested with WooCommerce 5.0 through 9.x.

= My tracking status isn't updating — what do I check? =

1. Confirm WP-Cron is running (check **Tools → Scheduled Actions** or use a cron monitoring plugin).
2. Check your usage in **TrackKaro → Settings** - if you have used your plan's allowance for the month, new syncs are paused until it resets or you upgrade.
3. Visit your TrackKaro dashboard for detailed tracking logs and diagnostic tools.

= Where can I get support? =

Open a ticket at [trackkaro.pk/panel/tickets](https://trackkaro.pk/panel/tickets) or email support@dango.pk .

== External Services ==

**This plugin is SERVICEWARE.** It has no standalone tracking functionality — it is a connector to the TrackKaro external platform. All courier tracking, status polling, API calls to courier companies, and shipment management are processed exclusively on TrackKaro's servers. None of this processing can be replicated locally by the plugin code itself.

**A TrackKaro account is required.** Accounts are free to create and include a permanent free monthly allowance; shipping beyond that allowance requires a paid PKR plan purchased at https://trackkaro.pk. The API key that connects this plugin to the service is issued only after signing up.

This plugin connects to the **TrackKaro** platform (operated by DANGO Solutions, https://solutions.dango.pk) to provide all courier tracking and order management functionality. This connection is mandatory — the plugin cannot function without it, as all courier API communication and data processing occurs on the TrackKaro servers, not locally on your WordPress site.

**Service details:**

* Service name: TrackKaro
* Service URL: https://trackkaro.pk
* Operated by: DANGO Solutions (https://solutions.dango.pk)
* Privacy Policy: https://trackkaro.pk/page/privacy-policy
* Terms of Service: https://trackkaro.pk/page/terms-of-service

**What data is sent and when:**

1. **On every tracking sync (every ~5 minutes for active orders):** The plugin sends your WooCommerce order's tracking number, courier name, and an internal order reference to the TrackKaro server. The server queries the courier's API and returns the current status, location, and event history.

2. **On plugin activation and settings save:** Your store's domain and the API token you entered are sent to TrackKaro to verify the connection. No customer data is included.

3. **On courier order creation:** When you create a shipment booking from the WooCommerce order screen, the customer's name, phone number, delivery address, order amount, and parcel details are sent to TrackKaro, which forwards them to the courier's booking API to create the shipment. This transmission only occurs when you explicitly click the "Generate Courier Order" button.

4. **On customer email notifications (if enabled):** The customer's email address (stored on the order) may be sent to TrackKaro's mail server to deliver tracking update emails. This feature is off by default and must be explicitly enabled by the shop owner.

**What is NOT sent:** Payment details, billing addresses, card numbers, or any information beyond what is listed above. TrackKaro acts solely as a tracking and logistics coordination service.

**No tracking functionality can be performed locally** — this plugin is specifically designed to work with the TrackKaro external service. If you do not agree to the TrackKaro Terms of Service and Privacy Policy, this plugin is not suitable for your store.

== Screenshots ==

1. **Order screen** — Add tracking number and courier directly on the WooCommerce order page.
2. **Order list** — Live courier status column in your WooCommerce Orders list.
3. **Branded tracking page** — Customer-facing delivery timeline on your own domain.
4. **Courier booking form** — Create shipment bookings without leaving WooCommerce.
5. **Dashboard widget** — At-a-glance shipment stats right on your WordPress dashboard.
6. **Settings page** — Paste your API token, choose your default courier, configure preferences.

== Changelog ==

= 1.0.115 =
* Improved: The plugin no longer checks in with TrackKaro on a timer to ask whether anything changed. The server now says so on the replies your store already receives, so a quiet store makes far fewer requests and a busy one effectively makes none beyond its own work. Courier lists, credential notices and your usage figure all still update — they now arrive rather than being fetched.
* Improved: Your plan usage in WooCommerce is updated from the regular status sync instead of a separate call, so it is current without costing a request.

= 1.0.114 =
* Fixed: Stores on the Free plan were told tracking was unlimited, then had shipments refused once the monthly allowance ran out. The settings screen now shows how much of this month's allowance you have used, and warns you before you reach it, instead of the first sign being a rejected shipment.
* Fixed: Usage was reported against a lifetime total rather than the current month, so on the first day of a new month a Free store could be flagged as out of allowance when it had just been reset.
* Changed: The old WooCommerce -> TrackKaro shortcut has been removed. Everything lives under the TrackKaro menu, which has been there since 1.0.112 - two entries for the same screen read like two different features.
* Improved: The checkout shipping estimate no longer asks the courier for a fresh quote every time WooCommerce recalculates the cart. Identical quotes are reused for an hour, which makes checkout noticeably lighter on busy stores.
* Changed: A bulk booking batch where SafeShip has nothing against anyone is no longer presented as though something needed attention.

= 1.0.113 =
* Fixed: The WordPress dashboard could be slow to load on stores with a lot of orders. The "parcels taking longer than usual" count was checking far more orders than it needed to; it now looks only at parcels old enough to possibly be running late.

= 1.0.112 =
* Added: **Insights** — a new TrackKaro menu with your own delivery analytics. See which courier actually delivers for you and how fast, which courier performs best in each city, which parcels are taking longer than usual, and what returns are costing you. Download any of it as CSV.
* Added: **Payments received** — upload the payment statement your courier gives you and TrackKaro checks it against what each parcel should have collected, showing anything that does not add up. Your statement is read once and never saved.
* Added: **Best courier for this city** shown beside each row when you bulk book. It comes from your own store's delivery history and never changes your courier choice for you — it is a note, not an instruction.
* Added: A quiet line on your WordPress dashboard when parcels are running longer than that courier usually takes for you. No emails, no alarms — it is there when you look, and it goes away on its own.
* Changed: TrackKaro now has its own menu instead of hiding under WooCommerce, so Insights and Settings both have a home. The old WooCommerce -> TrackKaro link still works.
* Changed: The bulk booking window now shows what SafeShip knows about every customer, not only the flagged ones — including their order history with you and whether SafeShip has checked them at all. Previously a clean customer and a customer nobody had checked looked identical.
* Note: All of the above is worked out on your own website, once a month, and never asks TrackKaro's servers for anything.

= 1.0.111 =
* Added: Dispatch Manifest — a printable rider handover sheet for any batch of booked orders, on any courier. Select orders in the orders list and choose "TrackKaro: Print Dispatch Manifest", or print it straight from the bulk booking window after the orders are created. The sheet lists every parcel with a scannable barcode, consignee, city, weight and COD amount, with totals and signature and CNIC boxes for the rider. Orders on different couriers print as separate signed sheets, since a rider only signs for their own parcels. This matters most on TCS, M&P, Daewoo and Bridge, which issue no load sheet at all — until now those merchants had no handover proof of any kind. Nothing is stored: the sheet is built from your orders each time you print it.

= 1.0.110 =
* Fixed: Marking an order "Completed" no longer stops tracking the parcel. Many stores mark an order complete the moment the courier collects it, which was silently ending tracking on parcels that had not been delivered yet — they froze at "Pending" and the customer never saw another update. Tracking now ends when the courier reports the parcel delivered, which is the only thing that actually proves it. Cancelled and refunded orders still stop tracking as before.
* Added: If you also use the free SafeShip Pakistan plugin, customers it has already flagged are now marked in the bulk booking window, so you can see them before committing a whole batch to a courier. Click a flag to see the details. This reads only what SafeShip already saved on the order, never blocks or unticks a booking, and can be turned off under Settings → Features.

= 1.0.109 =
* Fixed: The "TCS Official A4 - 3 Copies" label format could not actually be selected. It was offered in the settings dropdown and labelled the default, but was missing from the format allowlist, so saving silently reverted the setting to "A4 - 3 different orders per page".
* Fixed: Shipping labels no longer fetch the QR code from a third-party web service. The scan code is now generated locally as a Code128 barcode, so labels print correctly with no internet connection and no tracking numbers leave your store.
* Fixed: Shipping labels no longer load remote web fonts, so a label prints identically offline.
* Fixed: The default label format now agrees across the settings page, the saved default and the label renderer, which previously disagreed with each other.

= 1.0.108 =
* Added: Authentic TCS Official 3-Copy Airway Bill layout on A4 paper matching the original TCS slip specification (Consignee's Copy, Account's Copy, and Shipper's Copy).
* Added: Exact official TCS table grid structure with vector TCS brand mark, Code128 tracking barcode, large 2D QR matrix, Origin/Destination metadata, grey-header Shipper & Consignee boxes, COD Amount with barcode, Pieces, Weight, Fragile indicator, Product Details, Remarks, and Consignee disclaimer footer.
* Added: "TCS Official A4 - 3 Copies per page" as the new default printable label format for TCS and single-order airway bill printing.
* Improved: All shipping label layouts (A4 3-per-page multi-order, 4x6" thermal adhesive sticker, and A4 4-per-page 2x2 grid) enhanced with complete shipper return address, customer phone numbers, line items, and instructions with zero data truncation.

= 1.0.107 =
* Added: Full integration for Bridge Courier (`client.bridgecourier.com`).
* Added: Single order and Bulk order creation with Bridge Courier, including multi-carrier forwarding networks (Bridge NS, TCS, Leopards).
* Added: Dynamic auto-filtering of destination delivery cities based on selected shipper/forwarding network.
* Added: Configurable "Open Allowed" delivery option allowing consignees to inspect parcels before paying.
* Added: Real-time bulk tracking (up to 100 tracking numbers per query) and automatic airway bill PDF downloads for Bridge Courier.

= 1.0.106 =
* Added: Built-in Custom Shipping Label Generator with native browser printing (window.print). Supports multiple layouts: "A4 - 3 Labels per page" (default, 3 different orders per A4 sheet), "4x6 inch - Thermal Printer (Sticker Roll)", and "A4 - 4 Labels per page (2x2 Grid)".
* Added: High-contrast Code128 vector barcodes and scannable QR codes for tracking numbers and orders, fully recognized by TCS and all Pakistani courier scanners and rider mobile apps.
* Added: Custom Shipper Logo, Brand Name, and Return Address settings on printable labels.
* Added: Optional Packing Slip summary (item names, SKUs, quantities) and customer delivery notes on shipping labels.
* Added: "Print Shipping Label" button on single order screens alongside "Official Courier Slip".
* Added: "TrackKaro: Print Shipping Labels (A4 / Thermal)" bulk action for batch-printing dozens of shipping labels in 1 click.
* Zero server storage: labels and barcodes are compiled on-the-fly directly in the browser with 0 KB saved to server disk.

= 1.0.105 =
* Added: Enable Airway Bill download button on WooCommerce order detail for TCS Courier and other supported couriers.

= 1.0.104 =
* Fixed: Added missing `get_store_phone()` helper method in `Dango_TrackKar_Helpers` to resolve the fatal error and "Network error" during single and bulk order creation.

= 1.0.103 =
* Reverted: Made TCS Pickup Location (cost center) strictly required again to prevent merchants from accidentally skipping the location selection.

= 1.0.102 =
* Internal hotfix for TCS pickup locations.

= 1.0.101 =
* Fixed: Added shipper defaults for TCS in bulk order create to match single order creation.

= 1.0.100 =
* Added: Expected Delivery Date display on the frontend customer tracking page and synced with order tracking details.

= 1.0.99 =
* Fixed: Added missing shipper information fields (Shipper Name, Address, Phone, Origin City) to the TCS payload to prevent TCS rejecting orders.

= 1.0.98 =
* Fixed: The order screen had no TCS fields at all, so booking your first TCS order from an order could not be done — the pickup location could only be chosen in Bulk Create. TCS now has its own City and Pickup Location dropdowns there, both read from your TCS account, with the location you used last pre-selected.

= 1.0.97 =
* Fixed: M&P parcels were booked at a heavier weight than you entered — 0.5 kg was sent as 1 kg, moving every small parcel into the next charging band. M&P accepts decimal weights; TrackKaro now sends exactly what you type.
* Added: The weight box on Bulk Create follows each courier's own unit, so you never confirm a weight the courier will change behind you.
* Fixed: M&P airway bills print three labels to a sheet instead of one, and no longer print three copies of the same parcel by default.

= 1.0.96 =
* Changed: Amounts to collect are whole rupees now — no more ".00" on every row.
* Fixed: After booking a batch with a courier that issues no load sheet or airway bill (M&P, TCS, InstaWorld), the window said "generate the paperwork below" above an empty space. It now says what actually happened.
* Changed: The batch table fits without scrolling sideways on a normal screen, and the Result column no longer gets squeezed off the edge.
* Fixed: M&P pickup locations were always an empty dropdown, on both the order screen and Bulk Create. The cause was on the TrackKaro side and is fixed there — no settings change needed; your locations now appear, and the one you used last is pre-selected.
* Changed: If your TrackKaro plan runs out mid-batch, Bulk Create now stops and says so once, leaving the remaining orders untouched, instead of failing every row with the same message.
* Fixed: Downloading Airway Bills for a bulk batch stopped at 10 orders and refused the rest. There is no 10-order limit any more — ask for the whole batch and you get every label (as one PDF, or a zip when the courier cannot fit them all on one document).
* Added: Bulk Create can now pass the customer's own checkout note ("call before delivery") to the courier as Special Instructions, per order. Off by default, remembered once you set it, and it tells you how many orders in the batch actually have a note.

= 1.0.95 =
* Fixed: An order you typed in yourself from WooCommerce → Orders has no payment method, so Bulk Create read it as already paid and booked it with nothing to collect — you delivered the goods and the rider brought back no money. Bulk Create now asks whether the order has actually been paid, not which gateway it used.
* Added: Every row in Bulk Create now shows the order total (paid orders included) and the amount to collect at the door in a field you can edit before booking. Change it for a partial advance, a discount agreed on the phone, or anything the order total does not reflect; the change is written to the order notes.
* Added: A row set to collect nothing while money is still owed is highlighted in amber, so it can never happen by accident.
* Changed: The Bulk Create window is wider with a header that stays put while you scroll, so the city and the amount are readable at the same time.
* Added: Bulk Create Courier Orders now offers the Load Sheet (and Airway Bills, up to the courier limit of 10 parcels) right in the window as soon as the batch is booked — no need to close it and find the orders again.
* Changed: Closing the bulk window no longer re-ticks the orders you just booked. It could only do that reliably on the full orders list, so anyone working inside a saved filter got a partial selection back.

= 1.0.94 and earlier =
* Earlier releases added the courier integrations, COD booking, bulk create, the checkout city selector and shipping estimate, shipping labels, and the branded tracking page. Full history: https://trackkaro.pk/changelog

== Upgrade Notice ==

= 1.0.72 =
Remembers your last pickup address so you don't have to reselect it on every order. No settings changes required.

= 1.0.71 =
Adds DEX (Daraz Express) to the courier list so you can track DEX shipments. No settings changes required.

= 1.0.70 =
Adds the DEX (Daraz Express) tracking link. No settings changes required.

= 1.0.69 =
Tidier order box: the address check now runs as part of "Generate Courier Order", with an optional link if you want to check without booking.

= 1.0.68 =
Couriers that support it are now asked about the delivery address before you book, so you see any delivery risk up front. No settings changes required.

= 1.0.54 =
Sonic/Trax COD bookings can now be created directly from the WooCommerce order screen. No settings changes required.

= 1.0.53 =
Sonic/Trax orders can now download Airway Bill and Load Sheet PDFs from the order screen. No settings changes required.

= 1.0.52 =
Free-trial users now get trial-specific billing notices (days/quota remaining and a prompt to pick a plan). No settings changes required.

= 1.0.51 =
Monthly (postpaid) plans now get correct, informational overage notices instead of prepaid-style "recharge/expires" prompts. No settings changes required.

= 1.0.50 =
Adds a Cancel / Return action on the order screen and auto-fills your shop tracking link on connect. No settings changes required.

= 1.0.25 =
Fixes Leopards shippers list not appearing. After updating, clear plugin caches: WooCommerce → TrackKaro Settings → Save Settings (or wait for the 30-day cache to auto-clear).

= 1.0.24 =
Major Leopards Courier update: full booking form with Origin City, Shippers, Area, and Airway Bill download. Caches auto-clear on upgrade. No settings changes required.

= 1.0.19 =
Leopards tracking URLs have been updated. If you were seeing "tracking unavailable" errors for Leopards shipments, this update resolves them. No settings changes required — just update and you're done.
