7. Complete API Reference

7.1 HTML Attributes

Attributes are used for declarative configuration directly in HTML. Values are always strings.

Attribute	Type	Required	Description
`api-key`	string	Yes	API key assigned to the e-shop for authentication
`config`	JSON string	No	Widget configuration (see 7.5)

7.2 JavaScript Properties

Properties allow passing JS objects directly without JSON serialization.

Property	Type	Access	Description
`version`	string	read-only	Widget version
`widgetConfig`	WidgetConfig \| undefined	read/write	Widget configuration

7.3 JavaScript Methods

Method	Parameters	Return Type	Description
`configure(options)`	`Partial<WidgetConfig>`	void	Partial merge configuration — changes only specified parameters, preserves the rest
`open()`	—	void	Opens the widget (modal mode only)
`close()`	—	void	Closes the widget (modal mode only)
`getSelectedAccessPoint()`	—	SelectedAccessPointModel \| null	Returns the selected access point or null
`reset()`	—	void	Resets the widget to its default state

7.4 Custom Events

All events have the prefix ppl-accesspointwidget-, are emitted with bubbles: true and composed: true (pass through Shadow DOM).

Event	Payload (e.detail)	Description
`ppl-accesspointwidget-select`	SelectedAccessPointModel (see 7.8) - same type regardless of where the user selected the location	User selected an access point
`ppl-accesspointwidget-close`	null	Widget closed (without selection)
`ppl-accesspointwidget-error`	`{ code: string, message: string }`	Error during initialization or API call
`ppl-accesspointwidget-ready`	null	Widget successfully initialized

7.5 Configuration Parameters (WidgetConfig)

Complete list of parameters passed via the config attribute or widgetConfig property. Parameters marked (admin) are typically configured in the widget admin by api-key — override them via config only when a specific page must differ from the global setting.

General / UI

Parameter	Type	Default	Description
`theme`	string	`"PPL_THEME"`	Widget theme
`viewMode`	`"inline" \| "modal"`	from admin	(admin) Display mode — widget default is modal; admin can switch to inline. The config attribute on the element takes highest priority.
`closeButtonVisible`	boolean	—	Show close button
`defaultLang`	string	from admin / `"cs"`	(admin) Default language (see 7.6)
`langMenu`	boolean	—	Show language selection dropdown
`defaultCountry`	string	from admin / `"CZ"`	(admin) Default country (ISO 3166-1 alpha-2)
`allowedCountries`	string[]	from admin	(admin) Allowed countries (intersection with server configuration)
`countriesMenuDisabled`	boolean	`false`	Disable the country menu in the filter

Map Position

Parameter	Type	Description
`centeredToAddress`	string	Text address to center the map on
`centeredToLat`	number	Latitude (WGS84)
`centeredToLon`	number	Longitude (WGS84)

Package Dimensions

Parameter	Type	Description
`packageWeight`	number	Weight in kilograms
`packageWidth`	number	Width in centimetres
`packageHeight`	number	Height in centimetres
`packageLength`	number	Length in centimetres

Services

Parameter	Type	Description
`ageCheck`	boolean	Require age verification
`codRequired`	boolean	Cash on delivery required

Access Points

Parameter	Type	Description
`accessPointCode`	string	KM code of the access point to pre-select (format KM + 7 digits, e.g. KM1234567)
`disabledAccessPointTypes`	string[]	(admin) Disabled access point types — config is merged with the server list
`economyMode`	boolean	(admin) Economy mode (Smart2Box) — server value cannot be overridden

7.6 Supported Languages (defaultLang)

Code	Language
`bg`	Bulgarian
`cs`	Czech
`de`	German
`en`	English
`es`	Spanish
`fr`	French
`hr`	Croatian
`hu`	Hungarian
`it`	Italian
`nl`	Dutch
`no`	Norwegian
`pl`	Polish
`ro`	Romanian
`sk`	Slovak
`sl`	Slovenian

Insert into a website:

<ppl-access-point-widget
 id="pplWidget"
 api-key="**************************"
 config='{"viewMode":"modal","defaultCountry":"cz","defaultLang":"de"}'
></ppl-access-point-widget>

7.7 Access Point Types

Type	Description
`ParcelShop`	Staffed pickup location (PPL Parcel Shop)
`ParcelBox`	Self-service parcel locker (PPL Parcel Box)
`AlzaBox`	AlzaBox terminal (partner)

7.8 Selected Access Point Structure (SelectedAccessPointModel)

Object returned in e.detail of the ppl-accesspointwidget-select event and by the getSelectedAccessPoint() method:

The object always has the same structure, regardless of where the user selected the location (list of nearby places, place details, saved places, or the most recently selected place). The widget constructs it using data common to all sources; no additional API call is made for this purpose.

Note:
• All fields are optional (nullable). Always check for the presence of values when processing.
• typecontains the type name from the pickup point directory (ParcelShop, ParcelBox, AlzaBox), not the internal API code.
• accessPointType is deprecated and always holds the same value as type. It is retained for backward compatibility and will be removed in version 2.0; use only type for new integrations.
• The fields additionalNote (pickup point note) and urlPath (path to the location details on ppl.cz) are reserved; they are always present in the object but currently hold a null value. Only some of the data sources used to construct the object provide this information, meaning the object would otherwise differ depending on the selection method. Once this data is available across all sources, these fields will be populated without requiring further changes to the API contract. Account for them in your integration, but do not rely on their values for the time being.

7.9 Configuration Priority

Configuration is merged according to priority rules. The e-shop cannot extend server restrictions (set by the API key), only narrow them.

Server configuration (API claims by api-key) → Default settings from widget admin

Init parameters (config attribute / widgetConfig) → Overrides (or narrows) the default settings

URL parameters → Highest priority

Integration recommendations:

If you specify no parameters in config, the widget uses exclusively the default configuration from the admin — this is sufficient in most cases.

Use the config attribute only for parameters that differ from the default admin settings — typically dynamic cart data (packageWeight, codRequired, …), pre-selected access point (accessPointCode), map centering (centeredToAddress) or a page-level viewMode override.

Global settings (default language, country, allowed AP types, viewMode, economyMode) are best managed in the widget admin, not in the integration source code — changes then do not require a deployment.

Narrowing example: The server allows countries ["CZ", "SK", "HU"], the e-shop sets allowedCountries: ["CZ", "DE"] → the result is ["CZ"] (intersection). "DE" is not permitted by the server and will be ignored.

7. Complete API Reference

7.1 HTML Attributes#

7.2 JavaScript Properties#

7.3 JavaScript Methods#

7.4 Custom Events#

7.5 Configuration Parameters (WidgetConfig)#

General / UI#

Map Position#

Package Dimensions#

Services#

Access Points#

7.6 Supported Languages (defaultLang)#

7.7 Access Point Types#

7.8 Selected Access Point Structure (SelectedAccessPointModel)#

7.9 Configuration Priority#