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.

Classic Checkout Flow

Checkout Pickup Point Selector

The customer reaches the checkout page and sees the available shipping methods.
Upon selecting Balík na Poštu or BalikoBOX, a "Select Pickup Point" button appears below the shipping method.
If Hide Shipping Address Fields is enabled in settings, the shipping address form is automatically hidden.
The customer clicks the button to open the Pickup Point Picker dialog.
The customer searches for or browses pickup points on the map, then confirms their selection.
The selected pickup point name and a "Change" button replace the selector button.
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 — Detailed reference for the map dialog, search, and geolocation.
Block Checkout — How the plugin works with WooCommerce Blocks checkout.
Order Management — How pickup point data appears after the order is placed.

Pickup Point Picker

The pickup point picker is a modal dialog presented to customers at checkout when they need to choose a Slovenská Pošta pickup location. It combines a searchable list with an interactive map.

The dialog is built with jQuery UI Dialog, OpenLayers (map), and jQuery. All pickup point data is fetched from the local WordPress database via AJAX — no requests are made to external services during checkout.

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.

Search

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:

Sends the selected pickup point ID to the server via AJAX (wcsp_save_selected_pp).
The server validates the selection (existence, service match, weight limit if not bypassed).
The pickup point data is stored in the WooCommerce session.
The dialog closes.
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:

The picker dialog reopens.
The previously selected pickup point is highlighted in the results and on the map.
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 (

) 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:

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