VibeFox Sameday Easybox for PrestaShop — Help
Requirements
PrestaShop: 8.0 to 9.x.
PHP: 8.0 or later. The module refuses to install on older PHP versions.
Sameday API username and password: API access is part of a Sameday business account in Romania, Hungary or Bulgaria. Ask your Sameday account manager or the Sameday integration team. The credentials are often the same as for the eAWB portal (eawb.sameday.ro, .hu or .bg). For the demo API Sameday gives separate test credentials. Without an API username and password the carrier is not offered, because the customer could not choose a locker.
Counties in the address form: the Sameday estimate needs the county of the delivery address. PrestaShop has no counties for Romania, Hungary and Bulgaria by default. The module can add them for you (see easybox lockers below). Without them, prices come from your table or fallback cost.
VibeFox license key: bought on vibefox.net. One key works on one domain.
Installation
1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.
2. When the upload finishes, click Configure, or find VibeFox Sameday Easybox in the module list later and click Configure.
3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).
4. Enter your Sameday API username and API password, choose the Sameday country and click Save. The page should show "Connected to Sameday ... easybox lockers". Pickup point and Easybox service are filled in from your account.
5. Set your prices: Exchange rate of the estimate if your shop currency differs from the Sameday currency, and a Country prices row (for example * Default) or a Fallback cost.
6. If the page says the shop has no counties for your Sameday country, click Add counties in the easybox lockers section.
On install the module creates the carrier Sameday easybox with the delivery time text Delivery to a Sameday easybox locker. It is assigned to all customer groups and to the zone of Romania. You can change zones, customer groups, delivery time and logo in Shipping > Carriers. Do not set prices there: the price always comes from the module.
Configuration
All settings are on the module's Configure page, in six sections. The Save button of any section saves the whole page.
Above the settings the page shows the connection status: the Sameday host, the number of easybox lockers and when the list was updated, or that Sameday rejected the username or password. It also lists configuration problems, for example no credentials, no price, no exchange rate for the estimate, no counties, a shop weight unit the module does not know, or that the carrier was not found.
All prices and limits accept a comma or a point as the decimal separator (4,99 or 4.99). An invalid or negative number is not saved: a warning names the field, and the previous value is kept.
General
Enable/Disable: turns the carrier on or off. It is the same as the carrier status in Shipping > Carriers.
Name: the shipping method name shown to the customer (the carrier name). Default: Sameday easybox.
Tax status: None means the price is final. Taxable with a tax rule makes PrestaShop add that shipping tax on top of the price.
Sameday account (API)
When you save, the module logs in to Sameday and loads your services, pickup points and the easybox locker list. The list is refreshed daily.
API username: your Sameday API username.
API password: your Sameday API password. It is never shown again: leave the field empty to keep the saved one. Emptying the username removes the password too. If Sameday rejects it, it is not tried again for 10 minutes.
Sameday country: the country of your Sameday account: Romania (api.sameday.ro) (default), Hungary (api.sameday.hu) or Bulgaria (api.sameday.bg). Its lockers are offered, and the carrier is shown for this destination country only. When you change it, the carrier is also linked to the zone of the new country.
Test mode: uses the Sameday demo API (sameday-api.demo.zitec.com) with demo credentials.
Prices
The order of use is: the Sameday estimate (when Pickup point and Easybox service are set), then the country prices table, then the fallback cost. Table prices are entered in the shop default currency. Customers who pay in another currency see the price converted.
Pickup point: your Sameday pickup point, where Sameday collects the parcels. After a successful login it is a list of the pickup points of your account, and the default one is chosen automatically. Needed for the Sameday estimate. Choose - not set (price table only) - to use only the price table.
Easybox service: the Sameday service for easybox delivery, usually "Locker NextDay" (code LN), which is chosen automatically. Needed for the Sameday estimate.
Exchange rate of the estimate: Sameday estimates in the currency of your Sameday country: RON, HUF or BGN (EUR for Bulgarian shops that sell in euro). If your shop sells in another currency, enter the value of 1 unit of the Sameday currency in your shop currency, for example 0.20. The rate must be above 0. Without it the estimate is not used and the price table applies. Lev and euro are converted at the fixed rate automatically.
Table price: Per order charges the price once. Per item (price x quantity) multiplies it by the number of items. This applies to the table price and the fallback cost. The Sameday estimate is always for the whole parcel.
Country prices: a price per destination country and parcel weight. Click + Add country to add a row and the bin icon to remove one. Each row has a Price and weight columns: XS up to 1 kg, S 1–2 kg, M 2–3 kg, L 3–5 kg and XL over 5 kg. A weight column left at 0 uses the Price column. The * Default row is used for countries without their own row. A new row starts as * Default with all prices at 0, which means free shipping. Choose the country and enter the prices before you save, or remove the row. If the same country is in two rows, only the first one is kept when you save, and a warning says so. If a cell is not a valid number, the table is not saved.
Fallback cost: used when there is no Sameday estimate and the country table has no row for the destination. Leave it empty to not offer the carrier then.
Free shipping from: the cart subtotal (products that need shipping, after discounts, without tax) from which easybox delivery is free. When the subtotal reaches it, the carrier is offered at no cost and no price is looked up. Leave empty to never offer free shipping.
Availability
Minimum weight (kg): hide the carrier when the cart weighs less. The weight is converted from your shop weight unit (kg, g, lb or oz). Empty or 0 means no limit.
Maximum weight (kg): parcels heavier than this are not offered easybox delivery. Default: 30. Check the limit of your Sameday contract and the easybox box sizes. Empty or 0 means no limit. A minimum weight above the maximum weight is not saved: a warning says so, and the previous values are kept.
Minimum cart subtotal: offer the carrier only when the cart subtotal (products that need shipping, after discounts, without tax) reaches this amount.
Ignore shipping zones: when on, the carrier is offered for the countries selected below (the Sameday country when the list is empty), even if their zone is not set for the carrier. The carrier is then linked to every active zone, also zones created later. When you switch it off again, the carrier gets back the zones it had before. When off, the carrier is offered only in its zones from Shipping > Carriers.
Countries (ignore zones mode): the destination countries for that mode. Countries other than the Sameday country are skipped, and the page warns about them. This field is used only when Ignore shipping zones is on.
easybox lockers
Locker list: shows how many easybox lockers in how many cities are loaded and when. Refresh the locker list now loads it again. The list is refreshed when the settings are saved and, once it is older than a day, after a checkout request. For a fixed daily refresh, call the Cron URL shown here once a day from a cron job of your server. The URL contains a secret token. Without the token it answers with an error and does not contact Sameday.
Counties: the Sameday estimate needs the county of the address. If PrestaShop has no counties (states) for your Sameday country, click Add counties. The module adds the counties of Romania, Hungary or Bulgaria and the county field to the address form of that country. Counties that already exist are not added twice. When they are in place, the page shows their number.
Advanced
Debug log: writes rate calculations, API calls and locker choices to the file logs/vfd_sdeb_debug.log.php in the module folder, which cannot be read from the web. API errors are always logged. No password, token or customer personal data is logged. The Log field below shows the end of the file, with a Clear log button. Turn the log off when you are done.
Remove data on uninstall: when on, uninstalling the module deletes the settings and the carrier. Without it, uninstalling only switches the carrier off. The locker list and caches are always removed. The locker saved in orders is always kept.
How it works at checkout
When the shop calculates shipping for a cart, PrestaShop asks the module for the price of the Sameday easybox carrier. The module checks the conditions: delivery country of your Sameday account, API credentials and a usable locker list, the countries of Ignore shipping zones, cart weight and minimum cart subtotal. Products that do not need shipping (virtual products) are not counted. If free shipping applies, the customer sees the carrier at no cost.
Otherwise the module asks Sameday for an estimate, once the customer has entered a city and a county. It sends your pickup point and service, the parcel weight and the customer's street address, city, county and postcode. No name, e-mail or phone number is sent. Bucharest is sent as "Sector 1", like the official Sameday plugin. The estimate is converted to your shop currency. If there is no estimate (not set up, no city or county yet, error, no exchange rate), the price comes from the country table, then from the fallback cost. If there is no price, the carrier is hidden.
Sameday problems never break the checkout. The estimate is cached for 1 hour. An error is cached for 10 minutes. After a timeout or a server error no estimate is asked for 5 minutes. Requests time out after 15 seconds. The locker list is read from your server, not from Sameday, during checkout.
The carrier works in the delivery step of the Classic theme (PrestaShop 8) and the Hummingbird theme (PrestaShop 9).
The module does not create AWBs (shipments), print labels, track parcels or handle cash on delivery. It has no home courier delivery and no Sameday map widget. Create the AWB in the Sameday eAWB portal or your usual tool with the locker ID shown on the order.
Pickup points
When the customer selects the carrier, an easybox locker block appears below it with two lists: - Select city - and - Select easybox locker -. The city of the delivery address is pre-selected when it has lockers. Each locker shows its name and address. The choice is saved to the cart at once, so it stays when the delivery step is refreshed or the page reloads.
The locker is required. Without one, the customer cannot continue and sees "Please choose a Sameday easybox locker." When the customer clicks Continue, the server checks that the chosen locker is in the list. A forged or removed locker ID is refused with "The selected easybox locker is not available any more. Please choose another easybox locker." If the list cannot be loaded, the customer sees "The easybox lockers could not be loaded. Please try again in a moment or choose another shipping method." The name and address saved with the order come from the list, not from the browser. Once the order is placed, its locker no longer changes.
Admin order page: a Sameday easybox locker block with the name and address and the Locker ID for the Sameday AWB. If an easybox order has no locker, the block says "No easybox locker was selected for this order."
Order confirmation and order history pages: Sameday easybox locker: with the name and address.
Order e-mails: the locker name and address are added to the carrier in the order confirmation e-mail. The new order e-mail to the shop (Mail alerts module) also includes the Locker ID.
License key
The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Sameday Easybox is the first block on Modules > Module Manager > VibeFox Sameday Easybox > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-shipping-sameday-easybox and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).
If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.
One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop does not free its domain slot. Free the slot in your vibefox.net account.
Without an active key, the Sameday easybox carrier is not shown to customers at checkout and no price is requested or calculated. The PrestaShop storefront does not know that you are logged in to the back office, so the carrier is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected.
When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the module always removes the license key and license status. Reset of this module does not delete data, so the key and the status are kept.
Troubleshooting
Sameday easybox does not appear at checkout: check that the license is active, Enable/Disable is on, the API username and password are entered and the Configure page says "Connected to Sameday", and the destination country is the country of your Sameday account. Check that a price is available (Sameday estimate, country row, * Default row or Fallback cost) and the weight and subtotal limits. In Shipping > Carriers check that the carrier covers the zone of the customer's country and the customer's group, or turn on Ignore shipping zones. Products can also be limited to certain carriers on the product page. Turn on Debug log to see the reason in the Log field.
Sameday rejected the API username or password: check them and save again. Demo credentials work only with Test mode on, production credentials only with it off. Until then the stored locker list is offered, if there is one, and the Sameday estimate is not used.
The price comes from my table, not from Sameday: the estimate needs a Pickup point, the Easybox service, counties in the address form and, when your shop currency differs from the Sameday currency, the Exchange rate of the estimate. It is asked only after the customer has entered a city and a county. When Sameday is unreachable or returns an error, the table or fallback cost is used; the reason is in the log.
The locker list is old or missing: click Refresh the locker list now or save the settings. If a refresh fails, the previous list is used and the status says so. If the shop is in maintenance mode, the cron URL is blocked like the rest of the shop unless the IP of the cron server is allowed.
Shipping is free by mistake: check Free shipping from and the Country prices rows with a Price of 0, especially a * Default row added with + Add country and left unfilled.
Weight limits or weight columns do not match: if the page warns that the shop weight unit is not known, set kg, g, lb or oz in International > Localization (Local units).
The page says the Sameday easybox carrier was not found: the carrier was deleted in Shipping > Carriers. Reset the module in Modules > Module Manager to create it again. Reset keeps the settings and the status of an existing carrier.
Uninstall
Go to Modules > Module Manager, open the menu next to VibeFox Sameday Easybox and choose Uninstall. The license key and the license status are always removed. The stored locker list, the account check result and all caches are always removed. If Remove data on uninstall is on, the carrier is deleted (orders keep their history) and the settings and log are removed. If it is off, the carrier is only switched off and all settings are kept. Installing the module again gives the saved carrier back the status it had. Existing orders keep the saved locker.
Sameday and easybox are trademarks of their respective owners. This module is not affiliated with or endorsed by Sameday.