---
site_name: Toret dokumentace
site_url: https://documentation.toret.cz
contact_email: info@toret.cz

title: Toret TOPTRANS plugin documentation
url: https://documentation.toret.cz/en/toret-toptrans-plugin-documentation/
date: 2026-02-05
modified: 2026-07-07
author: tcirkl
type: page
---

# Toret TOPTRANS plugin documentation

You are on the documentation page for the TOPTRANS plugin for WooCommerce, which implements this shipping service into your e-shop.

You can purchase the TOPTRANS plugin here: [Toret TOPTRANS for WooCommerce](https://toret.cz/produkt/toptrans/)

Table Of Contents

1. Plugin Installation
2. Plugin Activation
3. Connecting to TOPTRANS
4. Main Settings
 - Mapy.com API Settings
5. Setting up Carriers in the TOPTRANS Plugin
 - Top Comfort Service
6. Shipping Zone Settings
7. Shipment Submission from Web to TOPTRANS
 - 1. Manual via button in order overview or order detail
 -
 - 2. Automatic package sending on order status change
8. Free Shipping
 - Free Shipping Only for Selected Products
9. Printing Labels
10. Cash on Delivery (Dobírka)
11. Displaying Shipment Status
 - Manual Shipment Status Update
 -
 - Automatic Shipment Status Update
12. Filters
 - Filters for Package Dimensions
13. Plugin testing

## Plugin Installation

Upon purchasing the plugin, you will receive a license key and a download link for the plugin zip file via email. You can find detailed instructions on how to install the plugin from your computer into WordPress [here](https://documentation.toret.cz/instalace-pluginu/).

## Plugin Activation

After installing the plugin, open the TOPTRANS plugin, insert the license key into the appropriate field, and click the button to activate.

![Toret TOPTRANS Plugin - activation](https://documentation.toret.cz/wp-content/uploads/2024/08/toptrans-licence.png "Toret TOPTRANS Plugin - activation")

## Connecting to TOPTRANS

To use the TOPTRANS plugin, you must have an account created at [zp.toptrans.cz](https://zp.toptrans.cz/).

After installing and activating the plugin, proceed to its settings. This is found in the section *Toret plugins → TOPTRANS*. To connect the plugin with your TOPTRANS account, you need to fill in your TOPTRANS account login credentials:

- Username (Uživatelské jméno)
- Password (Heslo)

![Toret TOPTRANS Plugin - API connection](https://documentation.toret.cz/wp-content/uploads/2024/08/toptrans-api.png "Toret TOPTRANS Plugin - API connection")

## Main Settings

In addition to API access settings, you will find global settings on the main page of the plugin *(Toret Plugins > TOPTRANS > Hlavní nastavení)*:

- Payment settings – for accepting COD payments
- Automatic package sending on order status change
- Checkout icon settings – custom icons can be uploaded, default displayed, or hidden
- Main settings (Hlavní nastavení)
 - Top Comfortservice
 - default values for description, weight, and dimensions of the package
 - administration dialogs and notifications
- Price settings – VAT, including fees in shipping price, tax class for COD fee
- Exchange rate source settings
- Mapy.com API settings (for calculating shipping price by distance)

### Mapy.com API Settings

To be able to **calculate shipping price according to distance**, it is necessary to connect the plugin with Mapy.com API. You do this in the Main Settings of the plugin *(Toret Plugins > TOPTRANS > Hlavní nastavení > Mapy.com API).*

![Toret TOPTRANS Plugin - Mapy.cz API settings](https://documentation.toret.cz/wp-content/uploads/2025/01/vlastni-poborky-mapy-api-1024x172.png "Toret TOPTRANS Plugin - Mapy.cz API settings")

To use REST API, you will need an account on the Mapy.com portal. Login/registration can be done [here](https://developer.mapy.cz/account/).

After [logging in to the portal](https://developer.mapy.cz/account/), create a project…

![Mapy.cz REST API settings](https://documentation.toret.cz/wp-content/uploads/2025/01/mapy-projekt-1-1024x542.png "Mapy.cz REST API settings")

…and get an API key. In the project overview, you will also see available credits and their usage, or the price for purchasing more. In the Basic tariff, 250,000 credits per month are available for free.

![Mapy.cz REST API settings 2](https://documentation.toret.cz/wp-content/uploads/2025/01/mapy-api-1-1024x542.png "Mapy.cz REST API settings 2")

Insert the copied API key into the REST API key field in the plugin and click Save.

[More information about REST API (Mapy.com)](https://developer.mapy.cz/rest-api/)

## Setting up Carriers in the TOPTRANS Plugin

Individual shipping methods can be found in the plugin on the tabs at the top of the screen *(Toret Plugins > TOPTRANS)*. The following shipping methods are available:

- Standard (standard delivery time within 24 hours of takeover)
- TOPTIME (morning delivery by 12:00)
- TOP-PRIVAT (evening delivery 16:00-20:00)
- TOP-WEEKEND (Saturday delivery – by 13:00)
- ROZVOZ PO AVIZACI (Delivery after notification – delivery after previous telephone agreement between carrier and customer)

All types of shipping can be set for the Czech Republic and Slovakia. If VAT is set in WooCommerce, set the price in the plugin without VAT.

![Toret TOPTRANS Plugin - carrier settings](https://documentation.toret.cz/wp-content/uploads/2024/08/toptrans-nastaveni-1024x562.png "Toret TOPTRANS Plugin - carrier settings")

**Under individual TOPTRANS shipping tabs, it is possible to set:**

- maximum weight and maximum dimension of the order
- dimension and weight check
- free shipping over amount and for specific products
- shipping price settings
 - uniform (flat)
 - according to total order weight
 - according to order dimensions
 - based on distance and weight
 - loading from API
- COD price uniformly or according to order price
- free COD over amount
- renaming of individual carriers is possible in the WooCommerce shipping zone directly in the carrier edit

> **Tip:** if you want to trigger free shipping or free COD at checkout e.g. from 500, set the value 499 in the plugin.

### **Top Comfort Service**

In the plugin *(Toret Plugins > TOPTRANS > Hlavní nastavení)*, it is possible to set the Top Comfort service for all shipping methods.  This involves carrying the shipment upstairs with the active assistance of the recipient, max. 80 kg/1 pc. Over 80 kg, a surcharge is charged for every started 80 kg.

For this service, you can set:

- Service text
- Service surcharge
- Surcharge label

![Toret TOPTRANS Plugin - TOP COMFORT settings](https://documentation.toret.cz/wp-content/uploads/2024/08/toptrans-top-comfort.png "Toret TOPTRANS Plugin - TOP COMFORT settings")![Toret TOPTRANS Plugin - TOP COMFORT in checkout](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-top-comfort-v-pokladne.png "Toret TOPTRANS Plugin - TOP COMFORT in checkout")

## Shipping Zone Settings

After setting up carriers in the TOPTRANS plugin, it is necessary to set up identically named carriers in WooCommerce shipping zones. Without setting them in shipping zones, carriers from the TOPTRANS plugin will not appear in checkout.

It is necessary to have a created shipping zone to which the shipping method from the TOPTRANS plugin will be added. Set the shipping method in *WooCommerce > Settings > Shipping > required shipping zone* *> Add shipping method.*

![Toret TOPTRANS Plugin - shipping zone settings](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-dopravni-zony-980x575-1.png "Toret TOPTRANS Plugin - shipping zone settings")

Select from the offered shipping methods and click Continue.

![Toret TOPTRANS Plugin - shipping zones](https://documentation.toret.cz/wp-content/uploads/2024/08/toptrans-zony-dopravy.png "Toret TOPTRANS Plugin - shipping zones")

In the next step, choose the Title and Description of the shipping method and Tax Status (Taxable or None). Click Create and save. The new shipping method is created.

![Toret TOPTRANS Plugin - shipping method settings detail](https://documentation.toret.cz/wp-content/uploads/2025/04/TOPTRANS-nastaveni-dopravni-metody-1024x553.png "Toret TOPTRANS Plugin - shipping method settings detail")

## Shipment Submission from Web to TOPTRANS

In the plugin, you have two options for submitting a shipment to the TOPTRANS system.

> Attention! Do not send the order to the TOPTRANS system unless you are ready to ship the package. By submitting the package, you indicate to TOPTRANS that you have the package ready for courier pickup.

### **1.** Manual via button in order overview or order detail

![Plugin Toret TOPTRANS podani zasilky z prehledu objednavek](https://documentation.toret.cz/wp-content/uploads/2026/07/Plugin-Toret-TOPTRANS-podani-zasilky-z-prehledu-objednavek.png "Plugin Toret TOPTRANS podani zasilky z prehledu objednavek")![Plugin Toret TOPTRANS podani zasilky z detailu objednavky](https://documentation.toret.cz/wp-content/uploads/2026/07/Plugin-Toret-TOPTRANS-podani-zasilky-z-detailu-objednavky.png "Plugin Toret TOPTRANS podani zasilky z detailu objednavky")

To submit the shipment, you can use the Send package (a) or Save package (b) button.

**Send package:**Used for the complete dispatch of the shipment – i.e., it sends data to the system, generates a label, a tracking number, and a carrier request.

**Save package:**Only transfers the data to the Toptrans system. You will see the order in your Toptrans account (in the Unconfirmed section), where you can still edit the shipping details. The shipping order can be completed either directly from your Toptrans account or from the e-shop administration (after saving, the Send package button will remain visible in the e-shop admin, so you can still confirm the shipping and generate labels later).[](http://documentation2.toret.cz/toptrans/wp-content/uploads/sites/56/2021/12/toret-toptrans-automaticke-podani-baliku.png)

### **2.** Automatic package sending on order status change

Automatic submission can be set in the plugin *(Toret plugins > TOPTRANS > Hlavní nastavení (Main Settings)).* In the case of automatic submission, the shipment is completely dispatched (including label generation, tracking number assignment, and carrier request).[](http://documentation2.toret.cz/toptrans/wp-content/uploads/sites/56/2021/12/toret-toptrans-automaticke-podani-baliku.png)

![Toret TOPTRANS Plugin - automatic submission settings](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-automaticke-podani-baliku.png "Toret TOPTRANS Plugin - automatic submission settings")

## Free Shipping

You set free shipping directly in the TOPTRANS plugin for each carrier. The free shipping plugin setting is “above” an amount, meaning free shipping activates on the web after exceeding the set amount in the cart.

**EXAMPLE:** If you want free shipping from 500, set the amount 499 in the plugin.

> **Tip:** If you have VAT set in WooCommerce, the value for triggering free shipping is entered without VAT.

The free shipping amount setting applies only to products; the shipping price is not included.

**EXAMPLE:** If you have free shipping set from 500, and the cart contains a product for 450 + shipping price 65 = 515 CZK, free shipping will not be activated. It is necessary to exceed the set price with the product, i.e., to activate free shipping set this way, you need to put product(s) worth at least 500 CZK into the cart.

### **Free Shipping Only for Selected Products**

In the plugin, it is possible to set free shipping only for selected products. Settings can be found for each product on the TOPTRANS tab.

![Toret TOPTRANS Plugin - free shipping per product](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-doprava-zdarma-pro-jednotlive-produkty-1.png "Toret TOPTRANS Plugin - free shipping per product")

Furthermore, it is necessary to enable this function in the plugin settings for the corresponding carrier.

![Toret TOPTRANS Plugin - enabling free shipping per product in settings](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-doprava-zdarma-pro-jednotlive-produkty-nastaveni-v-pluginu.png "Toret TOPTRANS Plugin - enabling free shipping per product in settings")

## Printing Labels

Labels of submitted packages can be downloaded directly in the website administration.

In the order overview for an order already submitted to the TOPTRANS system, click on the PDF document icon (see image) for the selected order. The label will be saved in PDF format, and then you can print it.

![Toret TOPTRANS Plugin - printing labels from overview](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-tisk-stitku-v-prehledu-objednavek-1024x121-1-1.png "Toret TOPTRANS Plugin - printing labels from overview")

For a submitted shipment, the label can also be downloaded in the order detail.

![Toret TOPTRANS Plugin - printing labels from detail](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-tisk-stitku-v-detailu-objednavky-1-1024x626.png "Toret TOPTRANS Plugin - printing labels from detail")

## Cash on Delivery (Dobírka)

For individual carriers, it is possible to set a COD surcharge for each country. For the surcharge to appear in the checkout and the information that the submitted package is COD to be transferred, it is necessary to enable the WooCommerce COD payment method (=cod) in WooCommerce settings.

In the plugin, you can set a uniform COD surcharge and a condition for triggering free COD. You can also scale the COD surcharge according to the total order price, including the condition for free COD (see screen).

![Toret TOPTRANS Plugin - COD settings](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-nastaveni-priplatku-dobirky.png "Toret TOPTRANS Plugin - COD settings")

In the main plugin settings *(Toret plugins >TOPTRANS > Hlavní nastavení)*, it is also necessary to set the bank account for COD payout.

![Toret TOPTRANS Plugin - COD bank account settings](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-nastaveni-uctu-pro-dobirku.png "Toret TOPTRANS Plugin - COD bank account settings")

Furthermore, in *Hlavní nastavení (Main Settings) > Ceny (Prices)*, you can enter the **COD tax class**. This can be fixed or determined by items in the cart. It is also possible to **include the COD fee in the shipping price** and not list it separately.

![Toret TOPTRANS Plugin - COD tax class settings](https://documentation.toret.cz/wp-content/uploads/2025/02/toptrans-dobirka-1024x280.png "Toret TOPTRANS Plugin - COD tax class settings")

## Displaying Shipment Status

The plugin includes a function that allows tracking the current shipment status in the order overview in the “Toptrans stav” column.

![Toret TOPTRANS Plugin - shipment status in transit](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-stav-zasilky-1024x121-1.png "Toret TOPTRANS Plugin - shipment status in transit")

### **Manual Shipment Status Update**

You can update the shipment status manually via the “refresh” icon. You can start the manual update in the order overview individually for each order or in the order detail.

![Toret TOPTRANS Plugin - manual shipment status update in overview](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-stav-zasilky-manualni-aktualizace-1024x121-1.png "Toret TOPTRANS Plugin - manual shipment status update in overview")![Toret TOPTRANS Plugin - manual shipment status update in detail](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-manualni-aktualizace-v-detailu-objednavky-1024x626-1-1.png "Toret TOPTRANS Plugin - manual shipment status update in detail")

### **Automatic Shipment Status Update**

If you want to automate shipment status updates, it is necessary to set up CRON on your hosting. You can find the custom CRON URL in the main plugin settings.

![Toret TOPTRANS Plugin - automatic shipment status loading CRON](https://documentation.toret.cz/wp-content/uploads/2024/06/toret-toptrans-url-cronu-1024x385-1.png "Toret TOPTRANS Plugin - automatic shipment status loading CRON")

## Filters

### Filters for Package Dimensions

- ttt_pack_width
- ttt_pack_height
- ttt_pack_length

Parameters: $rozmer, $order, $balik and $pocet_baliku

## Plugin testing

For testing purposes, you can use:

- the subdomain “dev.domainlicense” (with the same license as for the production website)
- localhost (127.0.0.1)

Purchased plugins will also work in these locations, and you can test their implementation and compatibility here before deploying them to the website and during its use.