Plugin Page

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

View Plugin
Documentation /

Checkout

How Checkout Integration Works

When a customer selects a Balík na Poštu or BalikoBOX shipping method at checkout, the plugin injects a pickup point selector below the shipping method. The customer must select a pickup point before they can complete their order.

The plugin supports both the classic WooCommerce shortcode checkout and the modern WooCommerce Blocks checkout.

Selector Modes

The plugin supports two pickup point selector implementations:

  • Pošta Widget (default) — The official Slovenská Pošta pickup point widget, loaded from Slovenská Pošta’s servers. Does not require a local pickup point database.
  • Built-in Map — An OpenLayers-based map dialog powered by the local pickup points database. Supports custom map icons, geolocation, and in-dialog weight warnings.

The active mode is controlled by the Use Pošta Widget setting in WP-Admin > Slovenská Pošta > Pickup Points. See Pickup Point Picker for a full description of both modes.

Classic Checkout Flow

Checkout Pickup Point Selector

  1. The customer reaches the checkout page and sees the available shipping methods.
  2. Upon selecting Balík na Poštu or BalikoBOX, a "Select Pickup Point" button appears below the shipping method.
  3. If Hide Shipping Address Fields is enabled in settings, the shipping address form is automatically hidden.
  4. The customer clicks the button to open the pickup point selector (Pošta Widget or built-in map, depending on settings).
  5. The customer selects a pickup point and confirms their choice.
  6. The selected pickup point name and a "Change" button replace the selector button.
  7. The customer completes checkout normally.

Order Validation

When the order is submitted, the plugin validates the pickup point selection server-side:

  • Selection required: If no pickup point has been selected and a Slovenská Pošta shipping method is active, the order is rejected with an error message asking the customer to select a pickup point.
  • Pickup point exists: The plugin verifies the selected pickup point ID exists in the database.
  • Service match: The selected pickup point must offer the service matching the chosen shipping method (BNP or BBOX).
  • Weight limit: If Bypass Weight Limit is disabled in settings, the plugin checks that the cart weight does not exceed the pickup point’s maximum accepted weight.

Session Storage

The selected pickup point is stored in the WooCommerce session under the key wcsp_selected_pickup_point. The session data includes:

  • id — database ID
  • ref_id — Slovenská Pošta reference ID
  • name — display name
  • street, number, city, zip, country — full address
  • service_code — BNP or BBOX

When the order is placed, this session data is transferred to order meta. The session is cleared after the order is created.

Address Override

If the Replace Shipping Address option is enabled in settings:

  • The order’s shipping first name, last name, and company are overwritten with the pickup point name.
  • The shipping address fields (street, city, postcode, country) are replaced with the pickup point’s address.

This ensures that if your order management system or shipping label generator reads the WooCommerce shipping address, it will see the pickup point location rather than the customer’s home address.

Shipping Address Field Visibility

The plugin dynamically shows or hides the shipping address form based on the selected shipping method:

  • When a Slovenská Pošta method is selected → address fields are hidden (if enabled in settings).
  • When a non-Slovenská Pošta method is selected → address fields are shown normally.
  • Switching between methods updates the field visibility without a page reload.

Pickup Point Picker

The pickup point picker is presented to customers at checkout when they select a Balík na Poštu or BalikoBOX shipping method. The plugin supports two selector implementations.

Selector Modes

Pošta Widget (Default)

When Use Pošta Widget is enabled (the default), the official Slovenská Pošta pickup point widget is used. The widget is loaded from Slovenská Pošta’s servers and embedded into the checkout page.

  • Does not depend on the local pickup points database.
  • The widget’s appearance and search behavior are controlled by Slovenská Pošta.
  • Map settings (default center, zoom, custom icons) configured in the plugin do not apply to the widget.
  • The selected pickup point is stored in the WooCommerce session identically to the built-in map mode.

To switch to the built-in map, disable Use Pošta Widget in WP-Admin > Slovenská Pošta > Pickup Points.

Built-in Map

When the Pošta Widget is disabled, the plugin shows its own OpenLayers-based map dialog. All pickup point data is fetched from the local WordPress database via AJAX — no requests are made to external services during checkout. This mode uses the Map Settings configuration and requires an up-to-date local pickup points database.

The rest of this page describes the built-in map mode.

Dialog Layout

The dialog is split into two panels:

┌─────────────────────────────────────────────────────────────┐
│  [ Search pickup points...          ] [🔍]  [📍 My Location] │
├───────────────────────┬─────────────────────────────────────┤
│                       │                                     │
│  Results List         │           Map                       │
│                       │                                     │
│  ● Pošta Bratislava   │   [OpenLayers map with pins]        │
│  ● Pošta Košice       │                                     │
│  ● BalikoBOX - Aupark │                                     │
│                       │   ┌──────────────────────────────┐  │
│                       │   │ Selected: Pošta Bratislava 1 │  │
│                       │   │ Obchodná 15, 811 06, BA      │  │
│                       │   │ Mon-Fri: 8:00-18:00          │  │
│                       │   │ [✓ Confirm Selection]        │  │
│                       │   └──────────────────────────────┘  │
└───────────────────────┴─────────────────────────────────────┘

Left panel: Search input with a loader indicator, a "My Location" geolocation button, and the results list.

Right panel: OpenLayers map with clustered pickup point markers, and a details panel showing the selected pickup point’s address, opening hours, and a confirm button.

Opening the Dialog

The dialog opens when the customer clicks the "Vyberte odberné miesto" (Select Pickup Point) button injected below the chosen shipping method.

On open:

  • The map is initialized with the configured default center and zoom.
  • All pickup points for the active service (BNP or BBOX) are plotted on the map as clustered markers.
  • If Auto-Geolocation is enabled in settings, the browser requests the customer’s location automatically. If permission is granted, the map centers on the customer’s location and nearby pickup points are listed.

Text Search:

  • The customer types a search term (minimum 2 characters) in the search input.
  • Results are fetched from the local database via AJAX, searching across: pickup point name, city, and postal code.
  • A maximum of 40 results is returned.
  • Each result shows the pickup point name, address, and — if the cart weight exceeds that point’s limit — a weight warning badge.

Geolocation ("My Location"):

  • Clicking the My Location button triggers the browser’s Geolocation API.
  • If permission is granted, the plugin finds the nearest pickup points using the Haversine distance formula.
  • Up to 50 nearby results are returned, sorted by distance.
  • The distance to each pickup point is shown in the results list.

Map Interaction

  • Markers: All pickup points for the current service are shown on the map. When zoomed out, nearby markers cluster into a single circle showing the count. Clicking a cluster zooms in to separate the markers.
  • Selecting from the map: Clicking a map marker highlights the corresponding pickup point in the results list and shows its details in the details panel on the right.
  • Selecting from the list: Clicking a result in the list pans and zooms the map to that pickup point and shows its details.
  • Selected marker: The selected pickup point uses a distinct icon (configurable in Map Settings).

Pickup Point Details Panel

When a pickup point is selected (from either the list or the map), the right panel shows:

  • Name of the pickup point.
  • Full address (street, number, city, postal code).
  • Opening hours table, formatted from the stored XML data.
  • A Confirm Selection button.

Weight Warnings

If the total cart weight exceeds a pickup point’s maximum accepted weight, a visual warning is shown:

  • In the results list, a warning badge is displayed next to the pickup point name.
  • In the details panel, a warning message is shown.

If "Bypass Weight Limit" is disabled (default):

  • Pickup points that cannot accept the cart weight are grayed out in the list and cannot be selected.

If "Bypass Weight Limit" is enabled:

  • Weight warnings are shown but do not block selection. The customer can still confirm a pickup point even if the weight limit is exceeded.

Confirming a Selection

Clicking Confirm Selection in the details panel:

  1. Sends the selected pickup point ID to the server via AJAX (wcsp_save_selected_pp).
  2. The server validates the selection (existence, service match, weight limit if not bypassed).
  3. The pickup point data is stored in the WooCommerce session.
  4. The dialog closes.
  5. The pickup point name is shown below the shipping method with a "Change" button.

The selection persists in the session for the duration of the checkout. If the customer changes their shipping method to a non-Slovenská Pošta option and back, the previous selection is cleared.

Changing a Selection

If the customer clicks "Change" after confirming a selection:

  1. The picker dialog reopens.
  2. The previously selected pickup point is highlighted in the results and on the map.
  3. The customer can search, browse, and select a different pickup point.

Service Filtering

The dialog automatically filters pickup points based on the selected shipping method:

  • Balík na Poštu: Shows post office branches. If Exclude BalikoBOX Locations is enabled on the shipping instance, BalikoBOX lockers are also hidden from this list.
  • BalikoBOX: Shows only BalikoBOX locker locations.

Switching between shipping methods at checkout automatically resets the current selection and re-filters the results.

Block Checkout

WooCommerce Blocks Checkout Support

The plugin supports both the classic WooCommerce shortcode checkout ([woocommerce_checkout]) and the modern WooCommerce Blocks checkout introduced in WooCommerce 8.3+.

Behavior

The pickup point picker dialog works identically in both checkout types. When a Slovenská Pošta method is selected, the "Select Pickup Point" button appears and the shipping address fields are hidden automatically.

Known Limitations

  • The plugin is not registered as a native WooCommerce Blocks extension and does not appear in the block editor sidebar.
  • Custom block themes that significantly alter the WooCommerce Checkout block structure may require testing.

Verifying Block Checkout Works

To verify the integration:

  1. Enable the Blocks checkout on your site (via WooCommerce > Settings > Advanced > Checkout page, or by using the Checkout block in your page editor).
  2. Add a product to the cart and proceed to checkout.
  3. Confirm the Slovenská Pošta shipping methods appear under the shipping step.
  4. Select a method and verify the "Select Pickup Point" button appears.
  5. Open the picker, select a pickup point, and confirm.
  6. Verify the shipping address fields are hidden (if configured) and the selected pickup point name is shown.
  7. Complete the order and verify the pickup point is saved to the order.

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

Privacy Policy / Terms of Service