Admin Settings

Accessing Settings

All plugin settings are found under WP-Admin > Slovenská Pošta. Access requires the manage_woocommerce capability (Shop Manager or Administrator role).

Settings Tabs

The settings panel is divided into seven tabs:

All settings are stored in WordPress as a single serialized option under the key wcsp_settings.

Settings Storage Key

All settings are stored in a single WordPress option:

Option name: wcsp_settings

Individual settings are accessed as array keys within this option, for example:

• wcsp_settings['replace_shipping_address']
• wcsp_settings['map_start_zoom']
• wcsp_settings['pickup_points_db_update_frequency']

When using filters or custom code to read these settings, use get_option('wcsp_settings') and access the relevant key.

Pickup Points

Pickup Points Tab

Navigate to WP-Admin > Slovenská Pošta > Pickup Points to access these settings.

---

Address Handling

These settings control how the selected pickup point address interacts with the WooCommerce order.

Replace Shipping Address with Pickup Point Address

Key: replace_shipping_address

When enabled, the order’s shipping address is automatically replaced with the pickup point’s address after the order is placed. The pickup point name is stored as the shipping company name on the order.

This is recommended for stores that use the shipping address to print labels or send to a fulfillment system, as it ensures the package is addressed to the pickup point rather than the customer’s home.

Hide Shipping Address Fields at Checkout

Key: hide_shipping_address_fields Default: Enabled

When enabled, the shipping address form fields are hidden on the checkout page whenever a Slovenská Pošta shipping method is selected. Customers only need to select a pickup point — they do not need to fill in a delivery address.

Disabling this setting shows the standard shipping address form even when a pickup method is chosen.

---

Display Settings

Controls where pickup point information is shown after an order is placed.

Show in Order Emails

Key: display_in_email Default: Yes

When enabled, a pickup point summary (name, address, and opening hours) is included in the WooCommerce order confirmation email sent to the customer.

Show on Thank You Page

Key: display_in_thank_you Default: Yes

When enabled, pickup point details are displayed on the order confirmation (thank you) page immediately after checkout.

Show in My Account — View Order

Key: display_in_view_order Default: Yes

When enabled, pickup point details are displayed when a logged-in customer views their order under My Account > Orders > View Order.

---

Weight Settings

These settings affect how cart weight is calculated for pickup point weight limit validation (determining whether a pickup point can accept the parcel). They do not affect shipping cost calculation — for that, see the Packing Material Weight setting on each shipping method instance.

Packaging Weight

Key: packaging_weight Unit: kg

An additional weight value added to the total cart weight on top of product weights. Use this to account for the weight of packaging materials (boxes, padding, etc.).

Enable Default Weight for Products Without Weight

Key: enable_default_weight

When enabled, products that do not have a weight defined in WooCommerce will use the Default Weight value below. When disabled, products without a weight are treated as weightless (0 kg).

Default Weight

Key: default_weight Unit: kg

The fallback weight used for products that have no weight set, when Enable Default Weight is active.

Allow Selection Despite Weight Warning

Key: bypass_weight_limit

When enabled, customers can still select a pickup point even if the cart weight exceeds that pickup point’s maximum accepted weight. A warning is shown to the customer but selection is not blocked.

When disabled (default), pickup points that cannot accept the cart weight are visually grayed out and cannot be selected.

---

Dimension Settings

These settings provide fallback dimensions for products that do not have dimensions set in WooCommerce, used for package validation.

Enable Default Dimensions for Products Without Dimensions

Key: enable_default_dimensions

When enabled, products without dimensions use the defaults below for package size validation.

Default Length / Width / Height

Keys: default_length, default_width, default_height Unit: cm

Fallback dimensions applied to products that have no dimensions set, when Enable Default Dimensions is active.

---

BalikoBOX Dimension Settings

These settings define the maximum package dimensions accepted by BalikoBOX lockers.

Maximum BalikoBOX Dimensions

Keys: bbox_max_length, bbox_max_width, bbox_max_height Defaults: 50 cm × 60 cm × 45 cm

These values define the maximum package size that can fit in a BalikoBOX locker. If the cart contains products whose combined dimensions exceed these values and box packing is enabled, a size warning is shown.

Allow Selection Despite BalikoBOX Size Warning

Key: bypass_size_validation_bbox

When enabled, customers can select a BalikoBOX pickup point even if the package size exceeds the maximum dimensions. A warning is shown but selection is not blocked.

Enable Box Packing Check for BalikoBOX

Key: enable_box_packing_bbox Default: Yes

When enabled, the plugin runs a bin-packing algorithm to check whether all cart items can physically fit together inside the BalikoBOX dimensions. If they cannot, a warning is shown.

When disabled, only individual product dimensions are checked against the maximum — not whether all items together fit.

---

Balík na Poštu Dimension Settings

Allow Selection Despite Balík na Poštu Size Warning

Key: bypass_size_validation_bnp

Same behavior as the BalikoBOX equivalent — controls whether customers can proceed past a size warning.

Enable Box Packing Check for Balík na Poštu

Key: enable_box_packing_bnp Default: Yes

When enabled, the bin-packing check is applied to the configurable Balík na Poštu box dimensions below.

Balík na Poštu Box Dimensions

Keys: bnp_box_length, bnp_box_width, bnp_box_height Defaults: 100 cm × 50 cm × 50 cm

The shipping box dimensions used for the Balík na Poštu box packing check. These should represent the largest box your store uses for Balík na Poštu shipments.

Note: These are your store’s box dimensions, not Slovenská Pošta’s limits. The hard Slovenská Pošta dimension limits (min face 14×9 cm, max single side 150 cm, max girth 300 cm) are enforced separately and cannot be disabled.

---

Order Behavior

Auto-Complete Orders

Key: auto_complete_orders

When enabled, WooCommerce orders placed with a Slovenská Pošta shipping method are automatically set to Completed status after payment. This is useful for stores that do not require manual order processing.

Hide Cash on Delivery When Pickup Method Is Selected

Key: hide_cod_for_pickup

When enabled, the WooCommerce Cash on Delivery payment method is hidden from the checkout payment options whenever a Slovenská Pošta shipping method is selected. Use this if you do not offer COD for pickup shipments.

Map Settings

Map Settings Tab

Navigate to WP-Admin > Slovenská Pošta > Map Settings to access these settings.

These settings control the appearance and behavior of the OpenLayers map in the Pickup Point Picker dialog shown to customers at checkout.

---

Default Map View

Starting Zoom Level

Key: map_start_zoom Default: 7 Range: 1 (world view) — 19 (street level)

The zoom level when the pickup point picker dialog first opens, before any search or geolocation is performed. The default value of 7 shows most of Slovakia in the map viewport.

Starting Latitude

Key: map_start_lat Default: 48.6690

The latitude coordinate for the map center on initial load.

Starting Longitude

Key: map_start_lng Default: 19.6990

The longitude coordinate for the map center on initial load.

Tip: The default coordinates (48.669°N, 19.699°E) represent the approximate geographic center of Slovakia. If your customer base is concentrated in a specific region, adjust these to center the map there.

---

Selection Behavior

Zoom Level on Pickup Point Selection

Key: map_selection_zoom Default: 14

When a customer selects a pickup point from the results list, the map animates to center on that point. This setting controls how far the map zooms in. Level 14 shows street-level detail.

Animation Speed

Key: map_animation_speed Default: 500 Unit: milliseconds

The duration of the pan and zoom animation when the map moves to a selected pickup point. Set to 0 to disable animation entirely.

Disable Zoom Animation

Key: map_disable_zoom_animation Default: No

When enabled, selecting a pickup point instantly jumps to it on the map instead of using a smooth zoom/pan animation. This overrides the Animation Speed setting — the map snaps to the selected location with no transition.

---

Geolocation

Auto-Request Geolocation on Dialog Open

Key: auto_geolocation Default: Yes

When enabled, the pickup point picker dialog automatically requests the customer’s browser location (via the Geolocation API) as soon as the dialog opens. If the customer grants permission, the map centers on their location and nearby pickup points are listed in the results.

When disabled, customers must manually click the "My Location" button to use geolocation.

Browser behavior: The browser will prompt the customer for location permission the first time. If the customer previously denied permission, the auto-request will silently fail and the map will show the default center position.

---

Custom Map Icons

You can replace the default map pin icons with custom images. Each icon type has three settings: the image URL, and the anchor point (x and y, expressed as decimals from 0 to 1) that defines which part of the image is placed on the map coordinate.

An anchor of 0.5, 1.0 places the bottom center of the image on the map point — appropriate for a standard map pin shape.

Cluster Icon

Keys: map_icon_cluster, map_icon_cluster_anchor_x, map_icon_cluster_anchor_y

The icon displayed when multiple pickup points are grouped into a cluster (shown when the map is zoomed out).

Regular Pickup Point Icon

Keys: map_icon_regular, map_icon_regular_anchor_x, map_icon_regular_anchor_y

The default map pin shown for individual, unselected pickup points.

Selected Pickup Point Icon

Keys: map_icon_selected, map_icon_selected_anchor_x, map_icon_selected_anchor_y

The map pin shown for the currently selected pickup point.

Image format: PNG or SVG images work best. Images should be hosted on your own domain or a reliable CDN. The anchor coordinates are decimal values between 0 and 1 (e.g., 0.5 = 50% from the left/top edge).

Pickup Points Database

Pickup Points DB Tab

Navigate to WP-Admin > Slovenská Pošta > Pickup Points DB to access these settings.

This tab provides tools to populate and refresh the local database of Slovenská Pošta pickup points. The plugin stores all pickup point data locally — no live API calls are made during checkout. This tab is where you keep that data current.

Note: The Pošta Widget does not use the local pickup points database. These settings only affect the built-in map mode used when Use Pošta Widget is disabled.

---

Database Status

The top of the tab displays current statistics:

• Balík na Poštu pickup points: Total count of BNP locations in the database.
• BalikoBOX locations: Total count of BalikoBOX locker locations.
• Last updated: The timestamp of the most recent successful database update.

---

Manual Update

Click Update Now to immediately fetch and import the latest pickup point data from the Slovenská Pošta XML feed.

Note: Updating this database does not change the data used by the Pošta Widget. The widget loads pickup points directly from Slovenská Pošta’s servers.

The update process:

1. Downloads the XML file from the configured URL (default: https://www.posta.sk/public/forms/zoznam_post.xml).
2. Parses the XML and validates the entries.
3. Safety check: If fewer than 100 valid entries are found, the update is aborted to prevent accidentally replacing the database with incomplete data.
4. Truncates and replaces the existing pickup point data.
5. Updates the "last updated" timestamp.

The process runs via AJAX in the background — the page displays a progress indicator and shows a success or error message on completion.

---

Automatic Updates

Enable Automatic Updates

Key: auto_update_enabled

When enabled, the plugin uses WP-Cron to automatically update the pickup point database on a schedule, without requiring manual intervention.

Note: Automatic database updates apply only to the built-in map mode. They are not used by the Pošta Widget.

Update Frequency

Key: auto_update_frequency Default: weekly

How often the automatic update runs. Available options:

Recommendation: Weekly updates are sufficient for most stores. Slovenská Pošta does not change pickup point data frequently, and daily updates are generally unnecessary.

WP-Cron dependency: Automatic updates rely on WP-Cron, which is triggered by site traffic. On low-traffic sites, scheduled events may not fire at their exact scheduled time. For guaranteed scheduling on low-traffic sites, consider using a real cron job to trigger wp-cron.php.

---

Customizing the XML Feed URL

By default, pickup point data is fetched from:

https://www.posta.sk/public/forms/zoznam_post.xml

To use a different URL (e.g., a local mirror or a custom feed), define the following constant in your wp-config.php:

define( 'WCSP_PICKUP_POINTS_XML_URL', 'https://your-custom-url.com/feed.xml' );

Tracking

Tracking Tab

Navigate to WP-Admin > Slovenská Pošta > Tracking to access these settings.

The tracking feature lets you attach a Slovenská Pošta tracking number to each order and display the shipment status to customers across the admin, emails, and order pages.

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

---

Display Settings

Enable Tracking

Key: tracking_enabled Default: Yes

Master toggle for the entire tracking feature. When disabled, no tracking information is shown anywhere and the background sync does not run.

Show in Order Emails

Key: tracking_in_email Default: Yes

When enabled, a tracking section is appended to customer-facing transactional emails (processing, completed, and on-hold orders). The section includes the tracking number as a clickable link and a "Track your parcel on Slovenská Pošta" link.

See Order Emails for details on the email output.

Show on Thank You Page

Key: tracking_in_thank_you Default: Yes

When enabled, a 5-step progress bar and event timeline are displayed below the order table on the order confirmation (Thank You) page — but only once a tracking number has been set on the order.

Show in My Account

Key: tracking_in_my_account Default: Yes

When enabled, a Tracking Number row is added to the order totals table on the My Account → View Order page. The tracking number is shown as a clickable link.

Show Admin Order List Column

Key: tracking_list_column Default: Yes

When enabled, a Tracking column is added to the WP-Admin orders list, appearing after the Order Total column. The column shows the tracking number as a color-coded status badge linked to the public tracking page, along with an icon to open the tracking detail modal.

---

Background Sync Settings

Background sync keeps cached tracking events up to date automatically. The events are fetched from the public Slovenská Pošta API and stored on the order, so pages load without making a live API call on every page view.

Sync Interval (hours)

Key: tracking_sync_interval Default: 2 Range: 1–24

Minimum number of hours between background sync attempts for the same order. An order that was synced within this interval will be skipped during the next cron run.

Sync Window (days)

Key: tracking_sync_days Default: 30 Range: 1–90

Only orders placed within this many days are included in the background sync. Older orders are skipped.

---

How Background Sync Works

A WP-Cron job runs every two hours and processes all eligible orders — orders with a tracking number, placed within the sync window, and not yet marked as final.

Night hours guard: Sync is skipped if the current server time is between 22:00 and 05:00 to avoid unnecessary API calls outside business hours.

Final status: Once an order reaches a delivered or returned status, it is marked as final (_wcsp_tracking_final = 1) and excluded from all future sync runs.

Manual refresh: In the admin order edit page, the Slovenská Pošta – Tracking metabox has a Refresh button that forces an immediate sync for that order, regardless of the sync interval or night-hours guard.

License

License Tab

Navigate to WP-Admin > Slovenská Pošta > License to manage your plugin license.

For full details on how licensing works, including the grace period and validation behavior, see License Activation.

---

License Key Field

Enter your license key in this field and click Activate License to activate the plugin on your domain.

License Status

This section shows the current license state:

• Status: Active, Inactive, Expired, Revoked, or Grace Period.
• Domain: The domain the license is currently activated on.
• Expiration: The license expiration date (if applicable).
• Last Validated: The timestamp of the most recent license check.

Activating and Deactivating

• Activate: Enter the license key and click Activate License. The plugin contacts the license server at webdevelop.hu to validate the key.
• Deactivate: Click Deactivate License to release the license from this domain. Do this before migrating your site to a new domain.

See License Activation for a complete walkthrough and explanation of validation behavior.