Marketplace Returns Control for WooCommerce — returns and unclaimed parcels under control

Marketplace Returns Control for WooCommerce is a module for shops that ship with Nova Poshta, Ukrposhta or Meest and sell on Rozetka, Prom or Epicentr. A parcel the customer never picked up costs twice: delivery both ways plus goods that are “somewhere on the road”. Worse, a carrier or a marketplace sometimes closes such a parcel as “delivered” or “returned” while it still sits at a branch. A week later nobody remembers that it had to be collected.

The module checks every waybill of your orders against the carrier (with the “Check now” button, in Pro also 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” — when the goods are really back on the shelf. Waybills and keys come from our Nova Poshta, Ukrposhta and Meest modules, so after installation there is usually nothing to fill in.

What the customer sees

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

What the admin gets

WooCommerce → “Returns control”: the parcel list with the number of problems on the menu item, and “Returns control settings”.

• One verdict per parcel. Every waybill gets exactly one verdict, and the list is split 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 order and 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 (WooCommerce, Rozetka, Prom, Epicentr), carrier, waybill, return waybill or order number.
• Adding by hand. The waybill of a parcel that is not among your WooCommerce orders, for example a marketplace order shipped by hand.

The box on the order screen shows the parcels of this order, the verdict, the “Return received” / “Cancel confirmation” / “Mark resolved” buttons and the history: who confirmed what and when. If no shipping module wrote the waybill, you can type it here and save it with the order.

• What to track. Which order meta keys hold waybills (our Nova Poshta, Ukrposhta, Meest, Marketplace Waybills modules or your own key), how many days back to take orders, which statuses to skip, after how many days without movement a parcel is “stuck”, how many days before the end of storage to warn.
• Carriers. Keys come from our shipping modules. The fields here are needed only if those modules are not installed or you want another key. Every carrier has “Save and test”.
• Order notes. A private note when a problem is found or a return is confirmed (can be turned off).

Pro: marketplaces, automation, Telegram

• Rozetka, Prom.ua, Epicentr. Cabinet orders with a waybill 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 it; the marketplace and the carrier disagree; the money was refunded to the customer before the goods came back. Credentials from our Marketplace Waybills, Epicentr Price & Stock Sync and Prom Model Guard modules are picked up automatically.
• The link to the WooCommerce order comes from Marketplace Waybills. Marketplace orders without a WooCommerce order get into the list too.

• Hourly check of carriers and marketplaces, no button needed.
• Morning e-mail digest: the parcels that need attention.
• Telegram: urgent cases (the marketplace closed it as received, the marketplace and the carrier disagree, money refunded before the goods, “returned” without your confirmation, a lost parcel) at once, the digest in the morning.
• Order status changes by itself: after a confirmed return (for example “Refunded”) and after a refusal (for example “On hold”), with a note in the order.
• CSV of the list with the current filters, for Excel and accounting.

How it works — step by step

1. As soon as an order is saved with a waybill written by a shipping module or by you, the module creates a parcel. Orders in statuses you skip (for example “Pending payment”) are not taken.
2. “Check now” (in Pro also every hour) asks the carriers: Nova Poshta and Ukrposhta in batches of up to 100 waybills, Meest one by one. Parcels never checked go first, then the stalest ones.
3. Every carrier’s answer is reduced to one state: in transit, at the branch, delivered, refused, coming back, returned to the sender, lost. For Nova Poshta the module takes the return waybill (except a redirect) and the storage end date.
4. In Pro the module reads Rozetka, Prom and Epicentr orders that have a waybill and adds the marketplace state and the refund to the parcel.
5. All of this plus your order status gives one verdict, from the most important to the ordinary: marketplace closed as received, disagreement, money before goods, “returned” without confirmation, lost, order status contradicts, storage ending, stuck.
6. Every change goes into the parcel history, in Pro also into Telegram or the morning digest. A return is closed only by your “Return received”.

Under the hood

• Own tables wp_ccmrc_parcels (one waybill — one row; the order and marketplace data are merged into it) and wp_ccmrc_events (history). Every query goes through $wpdb->prepare().
• Carrier 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 encrypted with AES-256 plus HMAC and never printed into HTML. Keys of our modules are read through their classes, nothing is copied.
• Security: every action checks a nonce and the manage_woocommerce capability. Anonymous requests to the handlers are rejected.
• Removal: uninstalling removes the tables, settings, transients, cron events and the module’s own order meta. Waybills written by shipping modules stay.

How to install

1. Download the free version catcode-marketplace-returns-control-for-woocommerce-1.0.0.zip with the button at the top of the page (or the Pro archive from your account after payment) and install it: Plugins → Add New → Upload Plugin. WooCommerce must be active.
2. WooCommerce → “Returns control settings”: check which order fields hold waybills. Keys from our shipping modules are picked up automatically — you will see “taken from the module …”.
3. WooCommerce → “Returns control” → “Check now”. Parcels appear in the tabs by verdict.
4. When a return has physically arrived, press “Return received” in the list or on the order screen.
5. 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 turn on the marketplaces and automation.