Skroutz Invoice Uploader

1. System Overview

The Skroutz Invoice Uploader is a WordPress/WooCommerce plugin module that automatically or manually uploads Oxygen (Pelatologio) invoices to the Skroutz Marketplace API after an order is placed through Skroutz.

The module bridges two external APIs:

There are two distinct upload flows depending on how the upload is triggered:

2. Requirements & Configuration

Plugin Settings to Enable

External Dependencies

• WooCommerce — order management, HPOS compatibility
• Oxygen Plugin — provides OxygenApi class and fires oxygen_invoice_created action
• WP-Cron — must be active; runs the queue worker hourly
• PHP cURL extension — required for multipart PDF upload to Skroutz API

Order Meta Required on WooCommerce Order

3. Flow A — Auto Invoice Creation (Queue)

This flow is triggered when an Oxygen invoice is automatically created because the order's WooCommerce status changed to the configured trigger status (e.g. processing).

Step-by-step sequence

Key hooks involved

4. Flow B — Manual Upload (Immediate)

This flow is triggered when an admin clicks "Upload Invoice to Skroutz" in the order edit page meta box. It runs synchronously — no delay, no cron needed.

Prerequisites before clicking the button

1. The order must have an Oxygen invoice already created (_oxygen_invoice meta must exist)
2. The Skroutz API token must be configured in Settings
3. The order should have a Skroutz order code (_skroutz_order_code meta)

Step-by-step sequence

What happens after a successful manual upload

• _skroutz_invoice_uploaded meta saved on the order with a datetime stamp
• A WooCommerce order note is added: "Invoice uploaded manually to Skroutz."
• An INFO log entry is written identifying both WC and Skroutz order IDs
• The queue row for this order is set to manually_uploaded — preventing the cron worker from re-uploading it
• If the order has no queue row yet, one is inserted with status manually_uploaded

Admin post handler

URL pattern: admin-post.php?action=skroutz_upload_invoice&order_id={ID}

Function: skroutz_handle_upload_invoice()

5. Queue System

The queue is a custom database table wp_skroutz_upload_queue that holds one row per order. Each row tracks both the WooCommerce order ID and the Skroutz order code for easy cross-referencing.

Queue item lifecycle

Skroutz order code resolution

When an order is enqueued, skroutz_queue_enqueue() immediately resolves and stores the Skroutz order code:

1. Read _skroutz_order_code meta from the WC order
2. If empty, fall back to $order->get_order_number()
3. Store the resolved code in the skroutz_order_code column

This means the dashboard always shows both IDs side-by-side for easier debugging.

Key queue functions

6. WP-Cron Worker

The queue is processed automatically by a WP-Cron scheduled event named oxygen_skroutz_cron_hook, which runs hourly.

Cron schedule

What the cron worker does per run

1. Check Skroutz API token is configured — abort if missing
2. Fetch up to 20 rows with status pending or retry
3. For each row: mark as processing, read skroutz_order_code from the row, call skroutz_do_upload_invoice()
4. On success: mark as completed
5. On failure: increment attempts; mark as retry if under max, or failed if exhausted
6. Log a summary line when finished

Manual trigger

The worker can also be triggered immediately from the dashboard via "Process Queue Now" (Quick Actions panel), without waiting for the next hourly cron.

If cron stops working

Use "Reschedule Cron" from the Quick Actions panel. This unschedules any existing event and registers a new hourly schedule starting immediately.

7. Core Upload Logic

Both flows (auto queue and manual) ultimately use the same upload steps. The queue worker calls skroutz_do_upload_invoice(int $order_id, string $api_token); the manual handler performs equivalent steps inline.

Upload steps inside skroutz_do_upload_invoice()

Return value

Skroutz API endpoint

POST https://api.sandbox.skroutz.dev/merchants/ecommerce/orders/{skroutz_order_code}/invoices

Headers:
  Authorization: Bearer {api_token}
  Accept: application/vnd.skroutz+json; version=3.0

Body (multipart/form-data):
  invoice_file: [PDF binary]

Error response format from Skroutz API

{
  "errors": [
    {
      "code": "order_error",
      "messages": ["Order not found"]
    }
  ]
}

The plugin parses this JSON and stores the human-readable messages (e.g. HTTP 404: Order not found) in the queue's message column and in the log file.

8. Retry & Failure Handling

Automatic retry flow

Manual recovery for failed items

When items reach failed status they will not be retried automatically. The cron worker only queries for pending and retry rows.

To re-queue failed items:

1. Go to Skroutz Invoice Uploader → Dashboard
2. Click the red "Reset Failed (N)" button (only visible when failed count > 0)
3. Confirm the dialog
4. All failed rows are reset to pending with attempts = 0
5. Click "Process Queue Now" or wait for the next cron run

9. Dashboard & Quick Actions

Accessible at WP Admin → Skroutz Invoice Uploader. Two tabs: Dashboard and Settings.

Stat cards

Shows live counts from the queue table (7 cards total):

Quick Actions (Dashboard tab)

Recent Queue Activity table

Shows the 20 most recently updated queue rows with columns:

• WC Order — linked to WC order edit page; shows attempt count
• Skroutz Order — the Skroutz order code stored at enqueue time
• Status — colour-coded badge
• Date — last updated_at timestamp
• Message — last result message (truncated with tooltip on hover)

Settings tab

Download Log File button (Settings tab)

Serves the most recently modified wc-logs/skroutz-uploader-*.log file as a direct browser download. If no log file exists, an error notice is shown.

Order edit page meta box

On every WooCommerce order edit page, a "Skroutz Invoice Uploader" meta box shows:

• Green tick + timestamp if the invoice was already uploaded (_skroutz_invoice_uploaded meta exists)
• "No invoice found" if the order has no Oxygen invoice yet
• "Upload Invoice to Skroutz" button — triggers Flow B (immediate manual upload)

10. Log Files

All logging goes through WooCommerce's logger (wc_get_logger()) with source tag skroutz-uploader.

Log identifier format

Since the recent update, all log messages that reference an order use the combined format:

WC#{woocommerce_order_id} / Skroutz#{skroutz_order_code}

Example: WC#1433 / Skroutz#260818-9607017

This makes it easy to search for either ID in the log file and immediately see the corresponding other ID.

Log message reference

11. Database Table

Table: wp_skroutz_upload_queue

Indexes

The table is created/upgraded automatically on every WordPress init request via dbDelta(). It is safe to call repeatedly — it only modifies the schema if it has changed. The skroutz_order_code column was added in August 2026 and will be added to existing installs automatically on the next page load.

12. Function Reference

13. Hook Reference