Plugin Page

WooCommerce Slovenská Pošta — BalíkoBOX, Balík na Poštu

View Plugin
Documentation /

Troubleshooting

FAQ

General

Does the plugin make live API calls to Slovenská Pošta during checkout?

It depends on the settings. If the Pošta Widget is enabled, pickup points are loaded dynamically directly from the Slovenská pošta servers. Otherwise, they are read from the local WordPress database.

Can I use both Balík na Poštu and BalikoBOX in the same shipping zone?

Yes. Both methods can be added to the same shipping zone simultaneously. Customers will see both options at checkout and can choose whichever they prefer.

Does the plugin support the WooCommerce Blocks checkout?

Yes. The plugin supports both the classic shortcode checkout and the modern WooCommerce Blocks checkout. See Block Checkout for details.

Is the plugin compatible with HPOS (High-Performance Order Storage)?

The plugin reads and writes order data using standard WooCommerce order meta functions (get_meta(), update_meta_data()), which are compatible with both legacy post-based storage and HPOS.

Shipping & Pricing

Why is my shipping method not showing at checkout?

Check the following:

  1. License active — the shipping methods are hidden if the license is not active. Check WP-Admin > Slovenská Pošta > License.
  2. Shipping zone configured — the method must be added to a shipping zone that matches the customer’s delivery address. Check WP-Admin > WooCommerce > Settings > Shipping.
  3. Method enabled — confirm the method is toggled on in the shipping zone (the toggle switch next to the method name).

Can I offer free shipping above a certain order value?

Yes. Set the Free Shipping Threshold on the shipping instance. If the cart subtotal reaches or exceeds this value, the shipping cost is automatically set to zero, regardless of the cost type setting.

How do I set up tiered pricing by weight?

  1. Edit the shipping method instance.
  2. Set Cost Type to Weight-Based.
  3. Add rows to the weight rules table: each row has a weight threshold (kg) and a price.
  4. Rules are evaluated in order — the first rule where cart weight ≤ threshold is used.

See Cost Calculation for examples.

Pickup Points

The pickup point picker shows no results. What should I do?

  1. Update the database — go to WP-Admin > Slovenská Pošta > Pickup Points DB and click Update Now. If the database is empty, no results will appear.
  2. Check the database stats — the DB tab shows the count of BNP and BBOX locations. If both show 0, the import failed.
  3. Check connectivity — the update requires the server to download the XML from https://www.posta.sk/public/forms/zoznam_post.xml. Confirm your server can reach this URL.
  4. Check for PHP errors — enable WP_DEBUG and WP_DEBUG_LOG and check wp-content/debug.log for errors during the update.

Can I exclude BalikoBOX lockers from the Balík na Poštu pickup list?

Yes. Edit the Balík na Poštu shipping instance and enable the Exclude BalikoBOX Locations option. BalikoBOX lockers will no longer appear in the BNP picker.

A pickup point’s opening hours seem incorrect. How are they updated?

Opening hours are imported from the Slovenská Pošta XML feed. To get the latest hours, trigger a manual database update from WP-Admin > Slovenská Pošta > Pickup Points DB. The frequency of opening hour changes in the feed depends on Slovenská Pošta’s update schedule.

Can customers select a pickup point that is over their cart’s weight limit?

By default, no — overweight pickup points are grayed out in the selector. To allow selection with a warning (but without blocking), enable Allow Selection Despite Weight Warning in WP-Admin > Slovenská Pošta > Pickup Points.

Tracking

Do I need an API key or account to use tracking?

No. The plugin generates a direct link to the public Slovenská Pošta tracking page for each order. Background event sync also uses the public Slovenská Pošta API endpoint — no credentials, API key, or account are required.

How do I add a tracking number to an order?

Open the order in WP-Admin > WooCommerce > Orders, find the Slovenská Pošta – Tracking sidebar metabox, enter the tracking number, and save. An order note is added automatically.

When does background sync run?

A WP-Cron job runs every two hours. It processes all orders with a tracking number that were placed within the configured sync window (default: 30 days) and have not yet reached a final status. Sync is skipped between 22:00 and 05:00 (server time).

Can I force a sync immediately?

Yes. Open the order edit page and click Refresh in the Slovenská Pošta – Tracking metabox. This triggers an immediate API call for that order.

Why did tracking stop updating for an order?

Once an order reaches a delivered or returned status, the plugin marks it as final and stops syncing it. You can verify this by checking the order’s _wcsp_tracking_final meta value. The Refresh button in the metabox still works on final orders.

Order Management

The pickup point address is not replacing the shipping address on my orders. What’s wrong?

Ensure Replace Shipping Address with Pickup Point Address is enabled in WP-Admin > Slovenská Pošta > Pickup Points.

The pickup point is not showing in order confirmation emails.

Check that Show in Order Emails is set to Yes in WP-Admin > Slovenská Pošta > Pickup Points.

Can I change the pickup point on an existing order from the admin?

There is no built-in UI for this. You can edit the _wcsp_pickup_point_* order meta fields directly through WordPress’s custom fields interface or a plugin like Advanced Custom Fields. See Order Management Overview for the list of meta keys.

ePodací Hárok

Do I need a separate contract with Slovenská Pošta to use ePodací Hárok?

Yes. The ePH API credentials (User ID and API Key) are obtained directly from Slovenská Pošta as part of their ePodací Hárok service agreement. They are separate from your plugin license.

Can I create an ePH shipment for orders that were not placed with a Slovenská Pošta shipping method?

Yes. The ePodací Hárok metabox is available on all WooCommerce orders, not only those using Balík na Poštu or BalikoBOX.

What happens if I click "Regenerate ePH" after a shipment is already registered?

All ePH data stored on the order (sheet ID, parcel number, label) is cleared, and the edit form reopens so you can create a new shipment. This does not cancel or reverse the previously registered shipment with Slovenská Pošta — contact them directly if you need to cancel a registered shipment.

The label download is failing. What should I check?

  • Confirm your User ID and API Key are entered correctly in WP-Admin > Slovenská Pošta > ePodací Hárok.
  • Check that the ZIP / Postal code in the Sender Information section is correctly formatted.
  • Enable API Call Logging and retry — the log will show the exact error response from Slovenská Pošta’s API.

Why is the "Delivery to Post Office / BalikoBOX / PoštaPOINT" (pr) service locked and cannot be unchecked?

For orders using Balík na Poštu or BalikoBOX shipping methods, the pr service is required by the ePH API to indicate pickup-point delivery. The plugin enforces this automatically and prevents it from being removed on those orders.

The COD amount is not pre-filling automatically. What’s wrong?

Open WP-Admin > Slovenská Pošta > ePodací Hárok > Cash on Delivery and make sure the WooCommerce payment method used by the order is selected in the COD Payment Methods list.

License

My license server is unreachable. Will the plugin stop working?

No. The plugin has a 7-day grace period when the license server cannot be reached. If the server remains unreachable for more than 7 days, the plugin will disable shipping methods until the license is successfully re-validated. See License Activation for full details.

I migrated my site to a new domain and the license isn’t working.

You need to deactivate the license on the old domain first, then activate it on the new domain. If the old site is no longer accessible, contact support at webdevelop.hu to release the license from the old domain.

Common Issues

Shipping Methods Not Appearing at Checkout

Symptoms: The Balík na Poštu or BalikoBOX options do not appear on the checkout page.

Checklist:

  1. License not active Navigate to WP-Admin > Slovenská Pošta > License and confirm the license status is Active. If not, activate the license. See License Activation.

  2. No matching shipping zone The customer’s shipping address must fall within a zone that has the method assigned. Check WP-Admin > WooCommerce > Settings > Shipping and ensure the method is added to the correct zone.

  3. Method disabled In the shipping zone, confirm the toggle switch next to the method name is enabled (blue/on).

  4. No rate returned If the method has a weight-based pricing table with no matching rule, it may return no rate. Ensure the weight rules cover the full range of expected cart weights, or add a catch-all final rule for heavy orders.

"Select Pickup Point" Button Not Showing

Symptoms: The customer has selected a Slovenská Pošta shipping method but no pickup point button appears.

Possible causes:

  • JavaScript error — open the browser console (F12) and check for JavaScript errors on the checkout page. A conflict with another plugin’s JavaScript is a common cause.
  • Script not enqueued — confirm wcsp-pp-checkout.js is loading on the checkout page by checking the page source or the Network tab in DevTools.
  • Block checkout not injecting — if using WooCommerce Blocks, the MutationObserver injection may fail if the block structure has changed. See Block Checkout.

Pickup Point Picker Shows No Results

Symptoms: The search returns no results, or "My Location" finds nothing.

Steps:

  1. Go to WP-Admin > Slovenská Pošta > Pickup Points DB and check the BNP/BBOX counts. If both are 0, the database has not been populated.
  2. Click Update Now and wait for the update to complete.
  3. If the update fails, check that your server can reach https://www.posta.sk/public/forms/zoznam_post.xml (try curl or a browser on the server).
  4. Check PHP error logs for import errors.
  5. If the safety check (100+ entries) is failing, the feed may be returning a partial or error response — check the raw URL in a browser.

Map Not Loading

Symptoms: The dialog opens but the map area is blank or shows a gray box.

Possible causes:

  • OpenLayers script blocked — check browser console for blocked resource errors. Ensure the plugin’s assets/vendor/ol/ scripts are not blocked by a CSP (Content Security Policy) header.
  • Map container has no height — if your theme overrides the dialog CSS with height: 0 on the map container, the map will not render. Inspect the #wcsp-pp-map element and ensure it has a positive height.
  • WebGL or canvas issues — OpenLayers uses the HTML5 Canvas API. In very old browsers or browsers with disabled WebGL, map rendering may fail. OpenLayers requires a modern browser.

Pickup Point Not Saved to Order

Symptoms: The customer selects a pickup point and completes checkout, but the pickup point does not appear in the WP-Admin order.

Possible causes:

  • Session not persisting — the pickup point is stored in the WooCommerce session. If the session is cleared between the pickup point selection and order submission (e.g., the customer navigates away and returns), the selection is lost. The checkout will show a validation error in this case.
  • AJAX save failed — check the browser console for errors on the wcsp_save_selected_pp AJAX call. A 403 or nonce error indicates a caching or security plugin conflict.
  • Caching plugin conflict — if a caching plugin serves a cached version of the checkout page with a stale nonce, AJAX calls will fail. Ensure the checkout page is excluded from caching.

Order Shipping Address Not Updated

Symptoms: The order’s shipping address still shows the customer’s home address rather than the pickup point address.

Solution: Enable Replace Shipping Address with Pickup Point Address in WP-Admin > Slovenská Pošta > Pickup Points.

Automatic Updates Not Running

Symptoms: The pickup point database is not updating automatically despite auto-updates being enabled.

Possible causes:

  • WP-Cron not running — on low-traffic sites, WP-Cron may not fire on schedule. Verify by checking whether other WP-Cron events are running (e.g., scheduled posts, WooCommerce cron). Consider setting up a real server cron. See Updating Pickup Points.
  • DISABLE_WP_CRON is set — if your wp-config.php has define('DISABLE_WP_CRON', true) without a server cron replacement, no cron events will run.

Tracking Column Not Showing in Order List

Symptom: No Tracking column appears in WP-Admin > WooCommerce > Orders.

Solution: Go to WP-Admin > Slovenská Pošta > Tracking and enable Show Admin Order List Column. Also confirm the master Enable Tracking toggle is on.

Tracking Section Not Showing on Customer Pages

Symptom: No tracking progress bar or tracking number is visible on the Thank You page or My Account order view.

Checklist:

  1. Tracking enabled — confirm Enable Tracking is on in WP-Admin > Slovenská Pošta > Tracking.
  2. Display setting — confirm Show on Thank You Page or Show in My Account is enabled.
  3. Tracking number set — tracking is only displayed once a tracking number has been saved to the order.
  4. Correct shipping method — the tracking section only appears on orders that used a Slovenská Pošta shipping method (wcsp_bnp or wcsp_bbox).

Tracking Events Not Updating

Symptom: The tracking number is set but events are not appearing or are out of date.

Possible causes:

  • Night-hours guard — background sync skips the 22:00–05:00 window. Wait until after 05:00 or use the Refresh button in the order edit metabox to force an immediate sync.
  • WP-Cron not running — the sync relies on WP-Cron. Confirm other cron tasks are running on your site. See Automatic Updates Not Running above.
  • Order outside sync window — orders older than the Sync Window (days) setting are not synced automatically. Increase the window or use the Refresh button.
  • Final status reached — orders with a delivered or returned event are marked as final and excluded from future syncs. This is expected behaviour.

Conflict with Other Plugins

Symptoms: Various unexpected behaviors — missing buttons, AJAX errors, JavaScript console errors.

Common conflicting plugin types:

  • Checkout customization plugins — plugins that reorder or remove checkout fields may interfere with how the plugin injects the pickup point selector.
  • Caching plugins — page or object caches can serve stale nonces, causing AJAX failures. Exclude the checkout page from caching.
  • Script optimization plugins — plugins that combine or defer JavaScript may break the plugin’s checkout scripts. Try excluding wcsp-pp-checkout.js and the OpenLayers scripts from optimization.
  • CSP plugins — Content Security Policy plugins that block inline scripts or external resources may prevent the map from loading.

Debugging tip: Deactivate all plugins except WooCommerce and this plugin, then test. Re-activate plugins one by one to identify the conflict.

© 2026 webdevelop.hu — Custom WordPress / WooCommerce Development & Migration Specialist — Contact

Privacy Policy / Terms of Service