Documentation /

Getting Started

Installation

System Requirements

Before installing the plugin, ensure your environment meets the following requirements:

  • PHP 8.1 or higher — the plugin is tested and compatible with PHP 8.1, 8.2, and 8.3.
  • WordPress 6.4 or higher — compatible with WordPress 6.4 and all subsequent releases.
  • WooCommerce 8.0 or higher — the plugin requires WooCommerce to be installed and active.
  • MySQL 5.7+ or MariaDB 10.3+ — required for the custom pickup point database tables.

No external API calls are made at runtime for pickup point data — all lookups are performed locally against your WordPress database.

Installation Methods

Upload via WP-Admin

  1. Download the woocommerce-slovenska-posta.zip plugin archive.
  2. In your WordPress dashboard, navigate to Plugins > Add New.
  3. Click Upload Plugin at the top of the page.
  4. Choose the .zip file and click Install Now.
  5. Once the upload completes, click Activate Plugin.

Manual Upload via FTP / SFTP

  1. Extract the .zip archive on your local machine.
  2. Connect to your server using an FTP or SFTP client.
  3. Upload the extracted woocommerce-slovenska-posta folder to wp-content/plugins/.
  4. In your WordPress dashboard, navigate to Plugins, locate the plugin in the list, and click Activate.

What Happens on Activation

When the plugin is activated for the first time, it automatically performs the following setup tasks:

  • Database tables — creates three custom database tables for storing pickup points, service codes (BNP/BBOX), and the many-to-many relationship between them.
  • Initial data import — imports the bundled feed/zoznam_post.xml file that ships with the plugin, populating the database immediately. No internet connection is required for this step.
  • Cron schedule — registers a WP-Cron event for automatic periodic pickup point database updates.
  • License redirect — redirects you to the Settings > License tab if no license key is present. See License Activation for details.

Deactivation

When the plugin is deactivated, the following occurs:

  • The three custom database tables are dropped and all pickup point data is deleted.
  • WP-Cron schedules (auto-update and license validation) are removed.
  • Plugin options and license data remain in wp_options.
  • Shipping method instances remain in WooCommerce shipping zones.

Warning: Deactivating the plugin permanently deletes all pickup point data. If you reactivate the plugin, the bundled XML will be re-imported automatically, and you can then run a fresh update from the Pickup Points Database settings tab.

Next Steps

After activation, proceed to License Activation to enter your license key and enable the plugin’s shipping methods.

License Activation

The plugin requires an active license key to function. Without a valid license, the shipping methods are hidden from the checkout and no pickup point data is served to customers. The admin settings remain accessible so you can manage settings and troubleshoot even with an inactive license.

Activating Your License

  1. Navigate to WP-Admin > Slovenská Pošta > License.
  2. Enter your license key in the License Key field.
  3. Click Activate License.
  4. The plugin contacts the license server at webdevelop.hu to validate the key against your domain.
  5. On success, the license status changes to Active and a confirmation notice is shown.

Tip: You can find your license key in your purchase confirmation email or in your customer account at webdevelop.hu.

Deactivating Your License

To move your license to a different domain:

  1. Navigate to WP-Admin > Slovenská Pošta > License.
  2. Click Deactivate License.
  3. The plugin sends a deactivation request to the license server, freeing the license for use on another domain.

Important: Always deactivate your license before migrating your site to a new domain. If you are unable to deactivate (e.g., the site is no longer accessible), contact support at webdevelop.hu.

How License Validation Works

The license is validated against the license server each time it is checked, with results cached for 24 hours in a WordPress transient. This means the plugin does not contact the server on every page load.

Grace period: If the license server is temporarily unreachable (network errors, server downtime), the plugin enters a 7-day grace period and continues to function normally. This prevents disruption due to temporary connectivity issues.

Explicit rejections: If the license server responds with an explicit rejection — such as an expired or revoked license — the plugin immediately disables shipping methods. The grace period does not apply to explicit rejections.

Validation outcomes:

Status Description
Active License is valid and the plugin is fully functional.
Expired License has passed its expiration date. Shipping methods are disabled.
Revoked License has been revoked. Shipping methods are disabled.
Inactive License key has not been entered or was deactivated.
Grace Period License server is unreachable but the plugin continues to operate for up to 7 days.

Effect of an Invalid License

When the license is not active:

  • Both shipping methods (wcsp_bnp and wcsp_bbox) are removed from WooCommerce’s available rates at checkout.
  • The pickup point selector is not rendered in the checkout.
  • All admin settings remain accessible so you can update the license key and re-activate.

Next Steps

With the license activated, proceed to First Steps to configure your shipping zones and go live.

First Steps

First-Time Setup Checklist

After installing the plugin and activating your license, follow these steps to get up and running.

1. Update the Pickup Points Database

The plugin ships with a pre-bundled snapshot of the Slovenská Pošta pickup point database, so the picker works out of the box without any manual import. However, the bundled data may be outdated by the time you install the plugin, so updating right away is recommended to ensure customers see the current list of locations.

  1. Navigate to WP-Admin > Slovenská Pošta > Pickup Points DB.
  2. Click Update Now to fetch the latest pickup point data from Slovenská Pošta.
  3. Wait for the update to complete. The page will display the total number of pickup points imported for each service (BNP and BBOX).

Why this matters: The plugin stores pickup point data locally for fast, server-side lookups. The bundled snapshot guarantees a working installation from day one, but a fresh update ensures opening hours, addresses, and newly added locations are all current.

See Updating Pickup Points for details on scheduling automatic updates.

2. Add Shipping Methods to Shipping Zones

  1. Navigate to WP-Admin > WooCommerce > Settings > Shipping.
  2. Create a new shipping zone (e.g., "Slovakia") or edit an existing one.
  3. Click Add Shipping Method.
  4. Select Balík na Poštu or BalikoBOX (or both) from the list.
  5. Click Add Shipping Method to confirm.
  6. Click the method name to open its settings and configure the title and pricing. See Balík na Poštu and BalikoBOX for full details.

3. Configure General Settings

Navigate to WP-Admin > Slovenská Pošta and review the key settings:

Pickup Points tab:

  • Set your default product weight and default product dimensions if your store has products without these values. This ensures the plugin can calculate weight limits and validate dimensions correctly.
  • Decide whether to replace the shipping address with the pickup point address on orders. This is recommended for most stores.
  • Decide whether to hide the shipping address fields at checkout when a pickup method is selected.

Map Settings tab:

  • Verify the default map center coordinates. The defaults are set to the geographic center of Slovakia (48.669°N, 19.699°E). Adjust if needed.
  • Enable Auto-Geolocation to automatically request the customer’s browser location when the picker dialog opens, for a better user experience.

4. Set Up Automatic Database Updates

To keep pickup point data current without manual intervention:

  1. Navigate to WP-Admin > Slovenská Pošta > Pickup Points DB.
  2. Enable Automatic Updates.
  3. Select an update frequency (daily, twice daily, weekly, twice monthly, or monthly).
  4. Save settings.

Weekly is recommended for most stores. See Updating Pickup Points for more details.

5. Test the Checkout Flow

  1. Add a product to your cart and proceed to checkout.
  2. Select a Slovenská Pošta shipping method (Balík na Poštu or BalikoBOX).
  3. Verify that the "Vyberte odberné miesto" (Select Pickup Point) button appears below the shipping method.
  4. Click the button to open the pickup point picker dialog.
  5. Test the search and map functionality.
  6. Select a pickup point and confirm.
  7. Complete the order and verify the pickup point appears in the order confirmation email and in the WP-Admin order detail.

Quick Reference: Where to Find Things

Task Location
Plugin settings WP-Admin > Slovenská Pošta
Shipping zone setup WP-Admin > WooCommerce > Settings > Shipping
Update pickup point data WP-Admin > Slovenská Pošta > Pickup Points DB
View orders with pickup points WP-Admin > WooCommerce > Orders
License management WP-Admin > Slovenská Pošta > License

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