Advanced Configuration & Overrides

You can dynamically influence the widget's behavior and appearance at runtime using the PickupSelectOverrides object.

This makes PickupSelect ideal for SAAS applications where you need to dynamically adjust the widget's behavior based on user preferences or system configurations.

Important: Overrides for countries, carriers, and groups act as filters. You can only allow items that are already enabled in the widget's admin interface. For example, if "Hungary" and "Slovakia" are enabled in the admin, but you set allowCountry('Germany') via override, no data will be displayed because Germany is not globally enabled for this widget. 
                
const settings = window.PickupSelectOverrides.init('wk_1234567890abcdef');

// Filter to a specific country
settings.allowCountry('Hungary');

// Filter to a specific carrier within a country
settings.allowCarrier('Hungary', 'Foxpost');

// Filter to specific pickup point groups (e.g., lockers, parcel shops)
settings.allowGroups('Hungary', 'Foxpost', ['Locker', 'Shop']);

// Appearance customization
settings.setConfig('theme', 'dark'); // or 'light'
settings.setConfig('primary_color', '#ff0000');
settings.setConfig('secondary_color', '#00ff00');

You can find all the supported countries, carriers, and pickup point groups in the countries, carriers, and pickup point group page.

Overrides are read once, when the widget starts. The allow… calls add up, so to apply a different filter with the same widget key (for example another shipping method), call reset() first and add a new <pickup-select> element: 

window.PickupSelectOverrides.reset('wk_1234567890abcdef');
const settings = window.PickupSelectOverrides.init('wk_1234567890abcdef');
settings.allowCarrier('Hungary', 'Packeta');

All countries and carriers

Turn on All countries and carriers in the widget settings to enable everything PickupSelect supports, including countries and carriers added later. Then use overrides to show only what a page needs.

Catalog endpoint

To build a settings screen for overrides (as the WooCommerce plugin does), list what a widget can show, with the names the overrides expect. It doesn't count towards your daily requests. 

GET https://www.pickupselect.com/api/catalog?apiKey=pk_1234567890abcdef&widgetKey=wk_1234567890abcdef
{
  "widget": { "name": "My shop", "all_carriers": true },
  "countries": [
    { "name": "Hungary", "code": "HU", "carriers": [
      { "name": "Foxpost", "logo_url": "…", "standalone": false,
        "groups": [ { "name": "Foxpost A-BOX", "code": "FOXPOST A-BOX" } ] }
    ] }
  ]
}

External API Functions

The widget provides functions that can be called from your own scripts, allowing you to control the map focus or selection based on external user input (like a checkout address form).

Function Description
selectPointById(pointId) Selects a specific pickup point by its ID and focuses the map on it.
focusMapToPostalCode(countryCode, postalCode) Moves the map focus to the coordinates of the specified country and postal code. 
                
// Example: Focusing the map based on a postal code input
await focusMapToPostalCode('HU', '1051');

// Example: Selecting a point programmatically
await selectPointById('999');