Developer Reference

The plugin is designed with extensibility in mind. Developers can customize behavior through:

Hooks & Filters — Action and filter hooks at key points in shipping cost calculation, pickup point display, and AJAX responses.
Template Reference — Overridable PHP templates for the checkout pickup point selector and dialog.

Text Domain

All translatable strings use the text domain wcsp.

__( 'Select pickup point', 'wcsp' );
_e( 'My Location', 'wcsp' );

Translation files (.po/.mo) are stored in the languages/ directory of the plugin. The plugin is fully translatable using standard WordPress i18n tools (Loco Translate, Poedit, etc.).

Plugin Class Structure

Class	File	Role
`WCSP_WooCommerce_Slovenska_Posta`	`woocommerce-slovenska-posta.php`	Bootstrap, license gate, enqueue scripts
`WCSP_Admin_Settings`	`includes/admin/class-admin-settings.php`	Settings page rendering and save
`WCSP_Shipping_Methods`	`includes/class-shipping-methods.php`	Register shipping method classes
`WCSP_Balik_Na_Postu_Shipping_Method`	`includes/shipping-methods/balik-na-postu.php`	BNP shipping calculation
`WCSP_BalikoBOX_Shipping_Method`	`includes/shipping-methods/balikobox.php`	BBOX shipping calculation
`WCSP_Checkout`	`includes/class-checkout.php`	Checkout UI injection and order validation
`WCSP_Pickup_Points`	`includes/class-pickup-points.php`	Database queries and data access
`WCSP_Ajax_Handlers`	`includes/class-ajax-handlers.php`	WordPress AJAX action handlers
`WCSP_Order_Display`	`includes/class-order-display.php`	Pickup point display on orders and emails
`WCSP_Package_Validator`	`includes/class-package-validator.php`	Dimension validation logic
`WCSP_Box_Packer`	`includes/class-box-packer.php`	Bin-packing algorithm
`WCSP_Cron`	`includes/class-cron.php`	Scheduled update management
`WCSP_License`	`includes/class-license-manager.php`	License validation and caching

PHP Requirements

PHP 8.1+ — the plugin uses PHP 8.1 language features including enums, readonly properties, and typed arguments.
Composer autoloader — the plugin uses Composer for dependency management. Production builds include the vendor/ directory. If working from source, run composer install in the plugin directory.

Hooks & Filters

Action Hooks

Shipping Calculation

`wcsp_before_calculate_shipping_bnp`

Fires before the Balík na Poštu shipping cost is calculated.

add_action( 'wcsp_before_calculate_shipping_bnp', function( $package ) {
    // $package = WooCommerce package array
} );

`wcsp_before_calculate_shipping_bbox`

Fires before the BalikoBOX shipping cost is calculated.

add_action( 'wcsp_before_calculate_shipping_bbox', function( $package ) {
    // $package = WooCommerce package array
} );

Pickup Point Validation (Classic Checkout)

`wcsp_before_validate_pickup_point_selection`

Fires before server-side pickup point validation runs during classic checkout.

add_action( 'wcsp_before_validate_pickup_point_selection', function( $chosen_service ) {
    // $chosen_service = string — 'BNP' or 'BBOX'
} );

`wcsp_validate_pickup_point_selection`

Fires after the pickup point has passed built-in validation. Use this to add custom validation.

add_action( 'wcsp_validate_pickup_point_selection', function( $selected_pp, $chosen_service ) {
    // $selected_pp    = array — selected pickup point session data
    // $chosen_service = string — 'BNP' or 'BBOX'
    // Call wc_add_notice( 'message', 'error' ) to block the order
}, 10, 2 );

Pickup Point Validation (Block Checkout)

`wcsp_before_validate_pickup_point_block_checkout`

Fires before validation runs during a WooCommerce Blocks checkout submission.

add_action( 'wcsp_before_validate_pickup_point_block_checkout', function( $order, $request, $chosen_service ) {
    // $order          = WC_Order
    // $request        = WP_REST_Request
    // $chosen_service = string — 'BNP' or 'BBOX'
}, 10, 3 );

`wcsp_validate_pickup_point_block_checkout`

Fires after built-in block checkout validation passes. Use this to add custom validation.

add_action( 'wcsp_validate_pickup_point_block_checkout', function( $selected_pp, $order, $request ) {
    // $selected_pp = array — selected pickup point session data
    // $order       = WC_Order
    // $request     = WP_REST_Request
}, 10, 3 );

Order Processing

`wcsp_apply_pickup_point_to_order`

Fires after the pickup point data has been written to the order (meta saved, address overridden if configured).

add_action( 'wcsp_apply_pickup_point_to_order', function( $order, $selected_pp ) {
    // $order       = WC_Order
    // $selected_pp = array — pickup point session data
}, 10, 2 );

Order Display

`wcsp_before_pickup_point_email_display` / `wcsp_after_pickup_point_email_display`

Fire before and after the pickup point section is rendered in order emails.

add_action( 'wcsp_before_pickup_point_email_display', function( $order, $pickup_point_id, $sent_to_admin, $plain_text ) {
    // $order           = WC_Order
    // $pickup_point_id = int
    // $sent_to_admin   = bool
    // $plain_text      = bool
}, 10, 4 );

`wcsp_before_pickup_point_admin_display` / `wcsp_after_pickup_point_admin_display`

Fire before and after the pickup point section is rendered in the WP-Admin order edit page.

add_action( 'wcsp_before_pickup_point_admin_display', function( $order, $pickup_point_id ) {
    // $order           = WC_Order
    // $pickup_point_id = int
}, 10, 2 );

`wcsp_before_pickup_point_order_details_display` / `wcsp_after_pickup_point_order_details_display`

Fire before and after the pickup point section is rendered on the Thank You page and My Account order view.

add_action( 'wcsp_before_pickup_point_order_details_display', function( $order, $pickup_point_id ) {
    // $order           = WC_Order
    // $pickup_point_id = int
}, 10, 2 );

Database Import

`wcsp_before_import_from_xml` / `wcsp_after_import_from_xml`

Fire before and after a pickup point XML import runs.

add_action( 'wcsp_before_import_from_xml', function( $local_file ) {
    // $local_file = string — absolute path to the XML file being imported
} );

add_action( 'wcsp_after_import_from_xml', function( $local_file, $parsed_data ) {
    // $local_file  = string — absolute path to the XML file
    // $parsed_data = array — all parsed pickup point rows
}, 10, 2 );

AJAX

`wcsp_before_save_selected_pickup_point`

Fires before a pickup point selection is saved to the WooCommerce session.

add_action( 'wcsp_before_save_selected_pickup_point', function( $pp_id, $pp_details ) {
    // $pp_id     = int   — pickup point database ID
    // $pp_details = object — full pickup point record from the database
}, 10, 2 );

Filter Hooks

Shipping Cost

`wcsp_shipping_cost_bnp` / `wcsp_shipping_cost_bbox`

Modify the final calculated shipping cost before the rate is added to WooCommerce.

add_filter( 'wcsp_shipping_cost_bnp', function( $cost, $package ) {
    // $cost    = float — calculated shipping cost
    // $package = array — WooCommerce package
    return $cost;
}, 10, 2 );

`wcsp_shipping_rate_bnp` / `wcsp_shipping_rate_bbox`

Modify the entire rate array before it is registered with WooCommerce.

add_filter( 'wcsp_shipping_rate_bnp', function( $rate, $package ) {
    // $rate = array — with keys: id, label, cost, taxes, meta_data, etc.
    return $rate;
}, 10, 2 );

Weight Calculation

`wcsp_item_weight_for_cost`

Modify the weight of a single cart item before it is added to the total weight for cost calculation.

add_filter( 'wcsp_item_weight_for_cost', function( $weight, $product, $item, $package ) {
    // $weight  = float      — raw product weight (before quantity multiplication)
    // $product = WC_Product
    // $item    = array      — WooCommerce cart item
    // $package = array      — WooCommerce package
    return $weight;
}, 10, 4 );

`wcsp_total_weight_for_cost_bnp` / `wcsp_total_weight_for_cost_bbox`

Modify the total cart weight used in the shipping cost calculation, after all items and instance packing weight have been summed.

add_filter( 'wcsp_total_weight_for_cost_bnp', function( $total_weight, $cart_weight, $packing_weight, $package ) {
    // $total_weight   = float — cart_weight + packing_weight
    // $cart_weight    = float — sum of all item weights
    // $packing_weight = float — instance-level packing material weight
    // $package        = array — WooCommerce package
    return $total_weight;
}, 10, 4 );

Dimension Validation

`wcsp_bnp_valid_dimensions` / `wcsp_bbox_valid_dimensions`

Override whether a product passes dimension validation.

add_filter( 'wcsp_bnp_valid_dimensions', function( $is_valid, $product, $validation, $package ) {
    // $is_valid   = bool       — current validation result
    // $product    = WC_Product
    // $validation = array      — full validation result array
    // $package    = array      — WooCommerce package
    return $is_valid;
}, 10, 4 );

`wcsp_bnp_box_packing_result` / `wcsp_bbox_box_packing_result`

Override the result of the bin-packing check.

add_filter( 'wcsp_bnp_box_packing_result', function( $fits, $pack_result, $package ) {
    // $fits        = bool  — whether items fit in the box
    // $pack_result = array — full packing result from WCSP_Box_Packer
    // $package     = array — WooCommerce package
    return $fits;
}, 10, 3 );

AJAX Response Filters

`wcsp_ajax_pickup_point_details`

Modify the pickup point details array returned by the wcsp_pp_get_pp_details AJAX action.

add_filter( 'wcsp_ajax_pickup_point_details', function( $response, $pp_id ) {
    // $response = array — full details array (id, name, address, opening_hours, etc.)
    // $pp_id    = int
    return $response;
}, 10, 2 );

`wcsp_ajax_search_pickup_points`

Modify the search results array returned by the wcsp_pp_search_pp AJAX action.

add_filter( 'wcsp_ajax_search_pickup_points', function( $results, $search ) {
    // $results = array  — array of pickup point result arrays
    // $search  = string — the search term used
    return $results;
}, 10, 2 );

`wcsp_ajax_closeby_pickup_points`

Modify the nearby results array returned by the wcsp_pp_get_closeby_pp AJAX action.

add_filter( 'wcsp_ajax_closeby_pickup_points', function( $results, $lat, $lng ) {
    // $results = array — array of nearby pickup point result arrays (with distance field)
    // $lat     = float
    // $lng     = float
    return $results;
}, 10, 3 );

`wcsp_selected_pickup_point_session_data`

Modify the data stored in the WooCommerce session when a pickup point is confirmed.

add_filter( 'wcsp_selected_pickup_point_session_data', function( $session_data ) {
    // $session_data = array — data to be stored in WC session
    return $session_data;
} );

Template Reference

The plugin provides two PHP templates that can be overridden in your theme. Template overriding follows the same convention as WooCommerce templates: copy the file to your theme’s directory and modify it there.

Template Override Path

Copy templates to your theme directory using this structure:

your-theme/
└── woocommerce-slovenska-posta/
    ├── checkout-pickup-point-select.php
    └── checkout-pickup-point-select-dialog.php

The plugin checks for theme overrides using locate_template() before loading from its own templates/ directory.

Templates

`checkout-pickup-point-select.php`

Plugin path: templates/checkout-pickup-point-select.php
Theme override path: your-theme/woocommerce-slovenska-posta/checkout-pickup-point-select.php

Purpose: Renders the inline pickup point selector shown below the shipping method at checkout. In the default implementation, this contains the "Select Pickup Point" / "Change" button and the display of the currently selected pickup point name.

Available variables:

Variable	Type	Description
`$selected_pickup_point`	`array`	null	Currently selected pickup point data from the WC session, or `null` if none selected
`$shipping_method`	`WC_Shipping_Rate`	The current shipping rate object

Default output:

<div class="wcsp-pickup-point-selector">
    <button id="wcsp-pp-toggle" type="button" class="button">
        Select Pickup Point
    </button>
</div>

When a pickup point is selected, the button text changes to the pickup point name with a "Change" link.

`checkout-pickup-point-select-dialog.php`

Plugin path: templates/checkout-pickup-point-select-dialog.php
Theme override path: your-theme/woocommerce-slovenska-posta/checkout-pickup-point-select-dialog.php

Purpose: Renders the HTML structure of the pickup point picker modal dialog. The JavaScript initializes the map, search, and interaction within this HTML structure.

Important: The element IDs and class names in this template are referenced by the JavaScript. If you rename them in your override, you must also update assets/js/wcsp-pp-checkout.js accordingly.

Key element IDs used by JavaScript:

Element ID	Purpose
`#wcsp-pp-dialog`	The root dialog container (jQuery UI Dialog target)
`#wcsp-pp-search`	Search text input
`#wcsp-pp-search-btn`	Search button
`#wcsp-pp-geolocation-btn`	"My Location" geolocation button
`#wcsp-pp-results`	Results list container
`#wcsp-pp-map`	OpenLayers map container
`#wcsp-pp-details`	Selected pickup point details panel
`#wcsp-pp-confirm-btn`	Confirm selection button
`#wcsp-pp-dialog-close`	Close dialog button

Default structure:

<div id="wcsp-pp-dialog" style="display:none;">
    <div class="wcsp-dialog-header">
        <button id="wcsp-pp-dialog-close">×</button>
    </div>
    <div class="wcsp-dialog-body">
        <div class="wcsp-dialog-left">
            <div class="wcsp-search-bar">
                <input id="wcsp-pp-search" type="text" placeholder="Search..." />
                <button id="wcsp-pp-search-btn">Search</button>
                <button id="wcsp-pp-geolocation-btn">My Location</button>
            </div>
            <div id="wcsp-pp-results"></div>
        </div>
        <div class="wcsp-dialog-right">
            <div id="wcsp-pp-map"></div>
            <div id="wcsp-pp-details"></div>
        </div>
    </div>
</div>

Stylesheets

The plugin’s frontend styles are loaded from assets/css/wcsp-pp-checkout.css. This file is enqueued on checkout pages and cannot be overridden via the template system. To customize styles:

Add CSS rules in your theme that override the plugin’s classes.
Use specificity or !important if needed to override the plugin’s defaults.

Key CSS classes:

Class	Purpose
`.wcsp-pickup-point-selector`	Wrapper around the inline selector button
`.wcsp-dialog-left`	Left panel of the dialog (search + results)
`.wcsp-dialog-right`	Right panel (map + details)
`.wcsp-result-item`	Individual result in the search list
`.wcsp-result-item.selected`	Currently selected result item
`.wcsp-weight-warning`	Weight warning badge on a result item
`.wcsp-result-item.weight-exceeded`	Grayed-out item when weight limit exceeded
`.wcsp-shipping-fields-hidden`	Applied to hide shipping address fields

Developer Reference

Text Domain

Plugin Class Structure

PHP Requirements

Hooks & Filters

Action Hooks

Shipping Calculation

wcsp_before_calculate_shipping_bnp

wcsp_before_calculate_shipping_bbox

Pickup Point Validation (Classic Checkout)

wcsp_before_validate_pickup_point_selection

wcsp_validate_pickup_point_selection

Pickup Point Validation (Block Checkout)

wcsp_before_validate_pickup_point_block_checkout

wcsp_validate_pickup_point_block_checkout

Order Processing

wcsp_apply_pickup_point_to_order

Order Display

wcsp_before_pickup_point_email_display / wcsp_after_pickup_point_email_display

wcsp_before_pickup_point_admin_display / wcsp_after_pickup_point_admin_display

wcsp_before_pickup_point_order_details_display / wcsp_after_pickup_point_order_details_display