# Symelo Bulgarian Shipping for WooCommerce

URL: https://dev.symelo.com/tools/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce

Speedy, Econt, Pigeon Express and BOX NOW for WooCommerce: office, locker and door delivery with live prices, waybills, tracking and the НАП file.

Version 1.0.0, released 2026-10-14. Requires WordPress 6.4 and PHP 7.4; tested up to WordPress 7.1. License: GPLv2 or later.

## Description

Symelo Bulgarian Shipping connects your WooCommerce shop to the Bulgarian couriers and parcel lockers, from the checkout to the delivered parcel.

#### At checkout

* **Office, locker and door delivery** for **Speedy**, **Econt**, **Pigeon Express** and **BOX NOW**. Each one is a normal WooCommerce shipping method, so you add it to your shipping zones and set its price like any other.
* **A picker that finds what customers type**: cities, offices and lockers in Cyrillic or Latin ("sofia", "Sofiq" and "соф" all find София), with the region next to villages that share a name.
* **Door delivery with the courier's own lists**: city, quarter, street, number, block, entrance, floor and apartment, so waybills are accepted the first time.
* **A map** to choose the office or locker, built in (OpenStreetMap, or the tile provider you choose) or the courier's own map where it has one (Speedy, Econt, BOX NOW).
* **Live prices** from Speedy, Econt and Pigeon Express, including the cash-on-delivery fee, or a fixed price, a weight table or free delivery. Free shipping from an order value or with a coupon, a markup in amount or percent, rounding.
* **The customer pays the courier** or **the price is in the order**: your choice per option.
* **Works with the Checkout block and the classic checkout**, takes your theme's fonts, colours and fields, and is easy to fine-tune with CSS custom properties.
* Hides the address fields the office or locker makes unnecessary, remembers returning customers' choices, and checks Bulgarian phone numbers.

#### After the order

* **Waybills** from the order screen (with a price check), in bulk from the orders list, or automatically when an order is paid. Parcels, weight, cash on delivery, declared value, "open/test before paying", SMS, contents and notes.
* **Print waybills**: a page with the labels waiting to be printed and the printed ones. Print one, or select many and get them all in one PDF, from every courier at once. Printed waybills are marked automatically (or by hand), with counts of parcels and cash on delivery for the selection, and a handover list for the courier to sign. Labels in A4 or A6.
* **Tracking** every few hours (BOX NOW also by webhook): status, history, and the tracking link in WooCommerce's emails and on the customer's order page. "Order shipped" and "Parcel ready for pickup" emails.
* **Cancellations, return waybills and courier pickup requests**, where the courier offers them.
* **Delivery alerts** by email: refused or returned parcels, delivery problems, failed automatic waybills, parcels without movement, cash on delivery that wasn't paid out in time.
* **Cash-on-delivery payouts** matched with your shipments (Speedy, Econt, Pigeon Express).
* **Order statuses** that follow the parcel, with optional "Shipped", "Delivered" and "Returned" statuses.
* **A log** of every courier request and answer (passwords and keys masked).

#### НАП (NRA) monthly file

For e-shops that register card and other non-cash payments with a "документ за регистриране на продажба" (Наредба Н-18, чл. 3, ал. 17):

* every paid order gets a 10-digit document number, and the customer receives the document with its QR code in the order emails;
* each month, preview and download the standardised audit file (Приложение № 38) in euro, checked against НАП's official schema, ready to upload by the 15th;
* choose the НАП payment code, virtual POS number and payment provider of each payment method; refunds are included automatically.

The file is built on your server; no order data leaves your site for it.

#### For developers

Filters: `symelo_shipping_capability`, `symelo_shipping_carriers`, `symelo_shipping_draft`, `symelo_shipping_rate_cost`, `symelo_shipping_method_available`, `symelo_shipping_cod_gateways`, `symelo_shipping_logo_url`, `symelo_shipping_http_timeout`, `symelo_shipping_alert`, `symelo_shipping_tabs`, `symelo_shipping_more_from_symelo`.

Actions: `symelo_shipping_loaded`, `symelo_shipping_shipment_created`, `symelo_shipping_shipment_canceled`, `symelo_shipping_return_created`, `symelo_shipping_create_failed`, `symelo_shipping_status_changed`, `symelo_shipping_carrier_saved`, `symelo_shipping_settings_saved`, `symelo_shipping_tab_{slug}`.

Constant: `SYMELO_SHIPPING_KEY` (encryption key for stored courier passwords and keys, at least 32 characters).

REST API (shop managers): `/wp-json/symelo-shipping/v1/` status, settings, carriers, carriers/{id}, carriers/{id}/test, carriers/{id}/sync, quote, orders/{id}/delivery, orders/{id}/quote, orders/{id}/shipments, shipments, shipments/printed, shipments/{id}, shipments/{id}/cancel, shipments/{id}/track, shipments/{id}/label, shipments/{id}/return, print, print/{job}, print/{job}/pdf, tracking/run, payouts/sync, logs, logs/{id}, nap/{year}/{month}, zones/setup, self-test. Public routes for the checkout picker: cities, points, map, streets, quarters. BOX NOW's webhook: webhook/boxnow (verified by its signature).

WP-CLI: `wp symelo-shipping status|test|sync|create|track|cancel|label|print|nap|payouts`.

## Installation

1. Install and activate the plugin (WooCommerce must be active).
2. Go to **WooCommerce → Bulgarian Shipping → Couriers**, enter your courier's API account and test the connection. Cities, offices and lockers are downloaded in the background.
3. Click **Add to a zone for Bulgaria** (or add the methods to your own shipping zone) and set their prices in **WooCommerce → Settings → Shipping**.
4. Optional: choose when waybills are created, the order statuses and alerts in **Waybills & automation**, and set up the **НАП report**.

You need an API account from each courier you use. Econt publishes a public demo account for trying the plugin (choose the Test environment); Pigeon Express and BOX NOW give test keys on request.

## Frequently Asked Questions

#### Does it work with the Checkout block?

Yes, and with the classic checkout. The picker appears under the shipping options in both.

#### Can customers pay the courier instead of paying for delivery in the order?

Yes. Set "The customer pays the delivery" to "To the courier on delivery" in the shipping method. The checkout shows the expected price, and the waybill says the recipient pays.

#### Where do prices come from?

Speedy, Econt and Pigeon Express calculate them live for the chosen office or address (cached for 30 minutes). BOX NOW has no price list in its API, so you set a fixed price or a weight table. Any method can also use a fixed price, a weight table or be free.

#### Is the shop's currency important?

The couriers work in euro, like Bulgaria since 1 January 2026. Shops that still show prices in leva are converted at the fixed rate of 1.95583.

#### What does the НАП file contain?

The orders delivered (or paid, as you choose) in the month whose payment method has a НАП code, with their items, discounts and VAT, and the refunds made in the month. Cash-on-delivery orders are left out unless you give their payment method a code.

#### Are my courier passwords safe?

They are stored encrypted, never shown again after saving, and masked in the log. Define `SYMELO_SHIPPING_KEY` in wp-config.php for a key that isn't in the database.

## External services

The plugin connects only to the couriers you set up, and only to do what you use: show offices, prices and streets at checkout, create and track waybills, print labels. Nothing is sent to Symelo LTD: there is no tracking, statistics or remote code.

#### Speedy

Used when you set up a Speedy account. Offices and cities are downloaded daily from api.speedy.bg; at checkout the plugin asks api.speedy.bg for street names and prices (with the destination, weight and cash-on-delivery amount); waybills, labels, cancellations, tracking, pickup requests and payout reports go to api.speedy.bg with the recipient's name, phone, email, delivery office or address and the parcel's details. If you choose Speedy's own map, the customer's browser loads it from services.speedy.bg when the map is opened. Tracking links point to speedy.bg.

* Terms: https://www.speedy.bg/en/terms-and-conditions
* Privacy policy: https://www.speedy.bg/en/gdpr

#### Econt

Used when you set up an Econt account (ee.econt.com, or demo.econt.com for the Test environment), in the same way as Speedy: cities, offices, streets and quarters, prices, waybills (with the recipient's details), labels, cancellations, tracking, courier requests and payout reports. If you choose Econt's own map, the customer's browser loads officelocator.econt.com when the map is opened. Tracking links point to econt.com.

* Terms: https://www.econt.com/en/econt-express/common-terms
* Privacy policy: https://www.econt.com/en/econt-express/privacy-policy

#### Pigeon Express

Used when you set up a Pigeon Express account (api.pigeonexpress.com, or api-demo.pigeonexpress.com for the Test environment), in the same way: cities, offices and lockers, street search, prices, waybills (with the recipient's details), labels, cancellations, tracking, courier requests and payout reports. Tracking links point to track.pigeonexpress.com.

* Terms: https://pigeonexpress.com/terms
* Privacy policy: https://pigeonexpress.com/privacy

#### BOX NOW

Used when you set up a BOX NOW account. The list of lockers is downloaded daily from locationapi-production.boxnow.bg (locationapi-stage.boxnow.bg for the Test environment); waybills (delivery requests with the recipient's name, phone, email and locker), labels, cancellations, returns and tracking go to api-production.boxnow.bg (api-stage.boxnow.bg). If you give BOX NOW support your webhook address, BOX NOW sends status updates to your site. If you choose BOX NOW's own map, the customer's browser loads it from widget-v5.boxnow.bg when the map is opened. Tracking links point to boxnow.bg.

* Terms: https://boxnow.bg/en/terms-of-use-for-shipping-services
* Privacy policy: https://boxnow.bg/en/personal-data-processing-notice-en

#### Map tiles (OpenStreetMap)

When the built-in map is on and a customer opens it, their browser loads map images from tile.openstreetmap.org (or from the tile provider you enter in the settings). The tile server receives the customer's IP address and the area shown. The map library (Leaflet) is part of the plugin.

* Tile usage policy: https://operations.osmfoundation.org/policies/tiles/
* Terms: https://osmfoundation.org/wiki/Terms_of_Use
* Privacy policy: https://osmfoundation.org/wiki/Privacy_Policy

## Credits

The map uses Leaflet 1.9.4 (BSD-2-Clause, https://leafletjs.com/), included in `assets/vendor/leaflet` with its readable source.

Speedy, Econt (ЕКОНТ), Pigeon Express and BOX NOW, and their logos, are trademarks of their owners. The plugin shows them only to tell customers and shop staff which courier delivers; it isn't made or endorsed by these companies.

## Upgrade Notice

#### 1.0.0
First release.

## Downloads

- [Symelo Bulgarian Shipping for WooCommerce 1.0.0](https://dev.symelo.com/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce/1.0.0/symelo-bulgarian-shipping-for-woocommerce-1.0.0.zip) (2026-10-14, 669 KB, SHA-256 f4d330365cea4e9b72bc0bed0dde8574caa04b19acf5db205f61b328d6b4f342)
  * First release: Speedy, Econt, Pigeon Express and BOX NOW; checkout picker with map for the Checkout block and the classic checkout; waybills, labels and the Print waybills page (one PDF for many labels), tracking, returns, alerts; the НАП monthly file.

## Documentation

- [Symelo Bulgarian Shipping for WooCommerce: user guide](https://dev.symelo.com/tools/wordpress-plugins/symelo-bulgarian-shipping-for-woocommerce/docs/user-guide)

## Related pages

- [All tools](https://dev.symelo.com/tools)
- [Agent documentation](https://dev.symelo.com/llms.txt)