Marketplace Returns Control for OpenCart — returns and uncollected parcels under control

Marketplace Returns Control for OpenCart is a module for stores that ship with Nova Poshta, Ukrposhta or Meest and sell on Rozetka, Prom or Epicentr. A parcel the buyer did not collect costs you twice: shipping there and back, plus goods that are “somewhere on the road”. Worse, the carrier or the marketplace sometimes closes such a parcel as “delivered” or “returned” while it still sits at the branch. A week later nobody remembers it had to be picked up.

The module checks every waybill of your orders with the carrier (with the Check now button, and in Pro every hour) and shows only the parcels that need a person. A return is closed not by the carrier status but by your Return received — that is, when the goods are really on the shelf. Waybills and keys come from our Nova Poshta Premium, Ukrposhta and Meest modules, so after installation there is usually nothing to fill in.

What the buyer sees

Buyers do not see the module: nothing changes in the storefront or the checkout, and there are no extra requests or scripts on the store pages. It works in the admin. Buyers only notice the effects: you call while the parcel is still at the branch, not after it has gone back; refunds for returns are paid when the goods really arrived; the order status matches what happened to the parcel.

What the admin gets

The Sales menu gets a Returns control item with the number of problem parcels. Settings are in Extensions → Extensions → Modules → Marketplace Returns Control.

• One verdict per parcel. Every waybill gets exactly one verdict, and the list splits into tabs: Needs attention, Returns, In transit, Done, All. Next to it — the carrier status with its code, the date of the change, the storage end date, the linked OpenCart order and the marketplace.
• Actions. Return received with a comment, Mark resolved (the parcel leaves Needs attention and comes back if its state changes again), delete, history.
• Filters and search. By source (OpenCart, Rozetka, Prom, Epicentr), carrier, waybill, return waybill or order number.
• Manual adding. Add a waybill by hand — for a parcel that is not among the OpenCart orders, for example a marketplace order shipped by hand.

The block on the order page shows the parcels of this order, the verdict, the Return received / Undo confirmation / Mark resolved buttons and the history: who confirmed what and when. If no shipping module wrote the waybill, you can enter it here together with the return waybill using Save and check.

• What to watch. Waybills from the tables of our Nova Poshta Premium, Ukrposhta and Meest modules (the module shows “found” itself), from another shipping module’s table or typed in the order. How many days of orders to take, which statuses to skip, after how many days without movement a parcel is “stuck”, how many days before storage ends to warn.
• Complete, Cancelled and Refunded statuses. The module compares the parcel state with them. The defaults are the standard Complete, Canceled and Refunded; if your store uses others, pick yours.
• Carriers. Keys come from our shipping modules. Own fields are needed only if those modules are not installed or a different key is needed here. Every carrier has Save and check.
• Order history. A history line without notifying the customer when a problem is found or a return is confirmed (can be switched off).

Pro: marketplaces, automation, Telegram

• Rozetka, Prom.ua, Epicentr. Cabinet orders with waybills are reconciled with the carrier and with your order. The module catches three situations: the marketplace closed the order as received while the carrier did not deliver the parcel; the marketplace and the carrier disagree; the buyer got the money back before the goods returned. Credentials from our Marketplace Waybills, Epicentr Price & Stock Sync and Prom Model Guard modules are picked up automatically.
• The link to the OpenCart order comes from Marketplace Waybills. Marketplace orders without an OpenCart order also get into the list.
• Hourly check of carriers and marketplaces without a button. In OpenCart 4 — with the built-in scheduler (Extensions → Cron Jobs); if your hosting does not run it, or in OpenCart 3 and 2.3 — with the cron URL from the settings, once an hour.
• Morning e-mail digest: the list of parcels that need attention.
• Telegram: urgent cases (marketplace closed it as received, marketplace and carrier disagree, money refunded before the goods, “returned” without your confirmation, parcel lost) at once, the digest in the morning.
• Order status changes by itself: after a confirmed return and after a refusal, with a history line that does not notify the customer.
• CSV of the list with the current filters, semicolon-separated with a BOM — opens in Excel without encoding trouble.

How it works — step by step

1. Check now (and in Pro every hour) first picks up new waybills: from the shipping modules’ tables, another table and the order block. It takes orders within the watch window (60 days by default); orders without a status and in the statuses you skip are left out.
2. Then the module asks the carriers: Nova Poshta and Ukrposhta in batches of up to 100 waybills, Meest one by one. Parcels that were never checked go first, then the oldest checked.
3. Each carrier answer is reduced to one state: in transit, at the branch, delivered, refused, returning, returned to the sender, lost. For Nova Poshta the module takes the return waybill (except redirection) and the date storage ends.
4. In Pro the module reads Rozetka, Prom and Epicentr orders with waybills and adds the marketplace state and the refund to the parcel.
5. All of that plus your order status gives one verdict, from the most important to the ordinary: marketplace closed it as received, disagreement, money before goods, “returned” without confirmation, lost, order status contradicts, storage ending, stuck.
6. Every change goes to the parcel history, in Pro also to Telegram or the morning digest. A return closes only with your Return received.

Under the hood

• No core edits. The menu and the order page block use OpenCart events, no OCMOD modifications. One class library is identical in the three builds, and the code is PHP 7.0 compatible.
• Own tables oc_cc_mrc_parcel (one row per waybill), oc_cc_mrc_event (history), oc_cc_mrc_order (waybills typed in orders), oc_cc_mrc_kv (service data). The shipping modules’ tables are only read.
• APIs: Nova Poshta TrackingDocument.getStatusDocuments, Ukrposhta Status Tracking, Meest openAPI tracking. In Pro — Rozetka Seller API, Prom.ua API, Epicentr Marketplace API.
• Keys and tokens are stored encrypted (AES with HMAC) and never printed in HTML. Keys of our modules are decrypted by the module itself, without loading their files.
• The licence lives in its own settings group: Save does not touch it, neither does uninstalling.
• Removal: uninstalling removes the events and the cron job; the parcel tables stay for a reinstall. The “Delete the parcels, their history and the settings when the module is uninstalled” checkbox removes them too.

How to install

1. OpenCart 4: Extensions → Installer → upload cc_mrc.ocmod.zip (do not rename the archive) and press Install. OpenCart 3: Extensions → Installer → cc_mrc-oc3.ocmod.zip. OpenCart 2.3: copy the contents of the upload/ folder from cc_mrc-oc2.ocmod.zip to the store root (FTP or the hosting file manager) — the 2.3 Installer does not copy files without a configured FTP.
2. Extensions → Extensions → Modules → Marketplace Returns Control → Install, then Edit.
3. What to watch: check that the shipping modules’ tables are marked “found”. Keys from our modules are picked up automatically — you will see “taken from the … module”.
4. Sales → Returns control → Check now. Parcels appear in the tabs by verdict.
5. When a return has physically arrived, press Return received in the list or on the order page.
6. For Pro: paste the licence key from the e-mail after payment or press Try Pro for 7 days in the Pro licence section, then switch on the marketplaces and automation. For OpenCart 3 and 2.3 add the cron URL from the settings to your hosting cron, once an hour.