VibeFox Sameday Easybox for Adobe Commerce — Help

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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 method is not offered, because the customer could not choose a locker.

Counties in the address: the Sameday estimate needs the county of the delivery address (the State/Province field of the Magento address form). Without a county, prices come from your table or fallback cost.

Magento cron: the locker list is refreshed by the standard Magento cron. Without cron the list is still loaded when you save the settings or click Refresh the locker list now.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-sameday-easybox-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/SamedayEasyboxShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_SamedayEasyboxShipping and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Delivery Methods and open VibeFox Sameday Easybox. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter your Sameday API username and API password, choose the Sameday country, set your prices (a Country prices row or a Fallback cost, and the Exchange rate of the estimate if your base currency differs from the Sameday currency), set Enable Sameday easybox to Yes and click Save Config. The Locker list and refresh row in the Easybox lockers section should show the number of easybox lockers. Pickup point ID and Easybox service ID are filled in from your account when they are empty.

The module adds the Sameday easybox shipping method to Magento. Customers see it as Sameday easybox - Parcel locker (method title and method name). It is off after installation (Enable Sameday easybox = No). The module also creates its own tables for the lockers chosen in carts and orders and for the locker list and caches.

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox Sameday Easybox, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Method title and Method name also for a store view. Only the value of Remove data on uninstall in the Default Config is used. Save Config saves the whole page. Amounts and weights accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Method title or Method name, longer than 64 bytes or with one of the characters < > ; = # { } (Enter a valid method title or name (1 to 64 bytes), without < > ; = # { }.), and a Sort order that is not a whole number (Sort order must be a whole number; negative numbers are allowed.).

Other mistakes do not stop the save, and a warning names them. A Pickup point ID or Easybox service ID that is not a positive number keeps its previous value (Sameday easybox: pickup_point_id must be a positive numeric ID; the previous value was kept.). An amount, weight or exchange rate that is not a number of 0 or more keeps its previous value (Sameday easybox: … is not a valid number; the previous value was kept.); an exchange rate of 0 is refused too. A minimum weight above the maximum weight keeps both previous weights (Sameday easybox: minimum weight is above maximum; both previous values were kept.).

When you save, the module logs in to Sameday and loads your services, pickup points and the easybox locker list. Empty Pickup point ID and Easybox service ID are filled in with the default pickup point of your account and the Locker NextDay service. While Enable Sameday easybox is Yes, warnings after the save tell you about configuration problems: Sameday easybox: enter API username and password; lockers cannot be offered without them.; Sameday easybox: configure estimate pickup point/service or a table/fallback price.; Sameday easybox: enter an exchange rate for the estimate currency.; Sameday easybox: only an API estimate is configured; a table/fallback keeps delivery available during outages.; Sameday easybox: lockers are offered only in the country of the Sameday account.; Sameday easybox: API credentials were rejected; any stored locker list is kept. and Sameday easybox: account check failed; any stored locker list is kept. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable Sameday easybox: shows or hides the method at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: Sameday easybox. Required, at most 64 bytes.

Method name: shown after the method title, as "Method title - Method name". Default: Parcel locker. Required, at most 64 bytes.

Sort order: the position among the shipping methods at checkout. A whole number, negative numbers are allowed.

Sameday account (API)

API username: your Sameday API username.

API password: your Sameday API password. It is stored encrypted and the field shows only a mask. Leave the mask to keep the saved password, type a new one to replace it, or clear the field and click Save Config to delete it. Clearing API username also removes the password. If Sameday rejects the login, it is not tried again for 10 minutes.

Sameday country: the country of your Sameday account: Romania (default), Hungary or Bulgaria. Its lockers are offered, and the method is shown for this destination country only.

Development environment: Yes uses the Sameday demo API (sameday-api.demo.zitec.com for Romania, and the Hungarian and Bulgarian demo hosts) with demo credentials. Default: No.

Prices

The order of use is: the Sameday estimate (when Pickup point ID and Easybox service ID are set), then the country prices table, then the fallback cost. Prices are in the base currency of your store, tax excluded; Magento shows them in the customer's currency. If your store charges tax on shipping, Magento adds it to these prices. Set this with Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping.

Pickup point ID: your Sameday pickup point, where Sameday collects the parcels. After a successful login a Choose from the account list next to the field shows the pickup points of your account; choosing one fills in the ID. Needed for the Sameday estimate. When it is empty, the default pickup point of your account is filled in at the next successful save.

Easybox service ID: the Sameday service for easybox delivery, usually Locker NextDay, which is chosen automatically. The Choose from the account list shows the services of your account. 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 stores with the euro as base currency). Multiply the API amount by this rate for the base currency: enter the value of 1 unit of the Sameday currency in your base currency, for example 0.20. Empty disables conversion; zero is refused. Without a rate, when the currencies differ, the estimate is not used and the price table applies. Lev and euro are converted at the fixed rate automatically.

Table price per: Per order (default) charges the price once. Per item multiplies it by the number of physical 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 cart weight. Click Add country to add a row and Delete to remove one. Each row has a country (or * All other countries for countries without their own row), a Price and weight columns: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL above. An empty cell counts as 0, and a weight column at 0 uses the Price column. A new row starts as * All other countries with empty prices, 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 (Sameday easybox: duplicate countries; only the first row was kept.). If a cell is not a valid number of 0 or more, the whole previous table is kept (Sameday easybox: invalid country price; the whole previous table was kept.).

Fallback cost: used when there is no Sameday estimate and the table has no row for the destination. Leave it empty to not offer the method 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 method is offered at no cost and no price is looked up. Leave empty to never offer free shipping.

Availability

Min cart weight (kg): hide the method when the cart weighs less. Empty or 0 means no limit.

Max cart 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 zero means no limit. Invalid limits or a minimum above the maximum keep the previous values.

Minimum cart subtotal: offer the method only when the cart subtotal (products that need shipping, after discounts, without tax) reaches this amount.

Ship to Applicable Countries: All Allowed Countries (the default) or Specific Countries. Whatever you choose, lockers are offered only in the country of your Sameday account.

Ship to Specific Countries: the destination countries for Specific Countries. It must include the Sameday country, otherwise the method is never shown.

Product weights are converted to kg from the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). Magento products have no standard dimensions, so volumetric weight is not calculated.

Easybox lockers

Locker list and refresh: shows the Sameday host, Production API or Demo API, how many easybox lockers in how many cities are loaded, when the list was last updated and the account status. If the last refresh failed, it adds The last refresh failed; the stored list is kept. Refresh the locker list now loads the list again for the current scope and answers The easybox locker list was refreshed. or The refresh failed; any stored locker list is kept. The Magento cron refreshes the list once it is older than a day and removes expired cache entries. There is no separate cron URL. Account country counties lists the county names the module recognises for the Sameday country.

Advanced

Debug log: writes rate calculations, API calls and locker list details to var/log/vfd_sdeb_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors are always logged, even when this is off. The API username and password are replaced with [redacted]. The file is rotated at 5 MB. Default: No.

Log contents: shows the size and the end of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the Sameday easybox settings, the log and the lockers chosen in carts that did not become orders (see Uninstall). The license key, the locker list and the caches are always removed. The lockers saved with orders are never deleted. Default: No.

How it works at checkout

At the shipping step Magento asks the module for the Sameday easybox price. The module checks the conditions: delivery country of your Sameday account and Ship to Applicable Countries, API credentials and a usable locker list, cart weight and minimum cart subtotal. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. If the cart subtotal reaches Free shipping from, the price is 0. A Magento cart price rule with free shipping also makes the price 0, but the conditions above still apply.

Otherwise the module asks Sameday for an estimate. 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". The estimate is converted to your base currency. If there is no estimate (not set up, no county, error, no exchange rate), the price comes from the country table, then from the fallback cost. If there is no price, the method 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. The locker list is read from your server, not from Sameday, during checkout, and it is kept in the module's own table, so it survives cache:flush.

The selector works in the standard Magento checkout (Luma). 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 Sameday easybox, the block Select an easybox locker appears under the shipping methods with two lists: City (Choose a city) and Easybox locker (Choose an easybox locker). The city of the delivery address is pre-selected when it has lockers, also for Bucharest sectors. Each locker shows its name and address. The choice is saved to the cart at once, so it stays when the shipping step is refreshed or the page reloads. If the address changes, the locker has to be chosen again. Reload locker list loads the lists again.

The locker is required. Without one, Next in the shipping step shows Please select an easybox locker. The chosen locker is checked against the list on the server when it is saved, when the customer clicks Next and again when the order is placed. A forged or removed locker ID is refused with The selected easybox locker is not available. or The selected easybox locker is no longer available. Please choose another locker. If the list cannot be loaded, the customer sees The easybox locker list is unavailable. Please try again later. 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.

If the customer cancels the payment on the payment page and the payment method restores the cart, the customer chooses a locker again and can place the order. The earlier order keeps its own locker.

Shipping description of the order: the module adds the locker name and address and its ID to the shipping method of the order, as "Sameday easybox - Parcel locker: name, address (ID 1234)". The customer sees it in the order in their account (or on the Orders and Returns page for guests) and in the order e-mails, and you see it on the admin order page. Magento keeps at most 255 characters of this text.

Order pages: a Sameday easybox locker block with the name and address and the Locker ID for the Sameday AWB is shown on Sales > Orders > View, Information tab, and on the order page in the customer account and for guests. The block also works for older orders and when the module is switched off.

Lockers chosen in carts that never became an order are removed after 30 days. Lockers saved with orders are never removed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Sameday Easybox is the first row of the VibeFox Sameday Easybox group in Stores > Configuration > Sales > Delivery Methods, 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 store. Below them are the line Product: magento-shipping-sameday-easybox and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Delivery Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 store 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 default store view, also when the installation has several websites or stores. Removing the key from the store does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, the Sameday easybox method is not shown to customers at checkout and no rate is calculated or requested. The Magento storefront does not know that you are logged in to the Admin, so the method 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. 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: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Sameday easybox does not appear at checkout: check that the license is active and Enable Sameday easybox is Yes for the website of the store, the API username and password are entered and Locker list and refresh shows lockers, and the destination country is the country of your Sameday account (and is in Ship to Specific Countries when Specific Countries is chosen). Check that a price is available (Sameday estimate, country row, * All other countries row or Fallback cost) and the weight and subtotal limits. Turn on Debug log to see the reason in Log contents.

Sameday rejected the API username or password: check them and save again. Demo credentials work only with Development environment = Yes, production credentials only with No. Until then the stored locker list is offered, if there is one.

The price comes from my table, not from Sameday: the estimate needs a Pickup point ID, an Easybox service ID, a county in the delivery address and, when your base currency differs from the Sameday currency, the Exchange rate of the estimate. 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, and check that the Magento cron runs. If a refresh fails, the previous list is used and the status says so.

The customer cannot continue: a locker must be chosen in the Select an easybox locker block. If the customer sees Sameday easybox is not available for this address., the method is not available for the current address any more (country, limits or price); the customer can choose another shipping method.

Shipping is free by mistake: check Free shipping from and the Country prices rows with a Price of 0 or empty, especially a * All other countries row added with Add country and left unfilled.

An order created in the Admin with Sameday easybox is refused: the Admin shows Please select an easybox locker. A locker can be chosen only in the storefront checkout. Use another shipping method for orders created in the Admin.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key, the settings and the saved lockers stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_SamedayEasyboxShipping. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_SamedayEasyboxShipping to remove the data, then bin/magento module:disable Vibefox_SamedayEasyboxShipping, delete the folder app/code/Vibefox/SamedayEasyboxShipping and run bin/magento setup:upgrade.

The license key, the license status, the stored locker list and all caches are always removed. If Remove data on uninstall is Yes, the Sameday easybox settings, the log and the lockers chosen in carts without an order are removed too. If it is No, the settings, the log and those cart choices are kept for a re-install. The lockers saved with orders and the shipping descriptions of orders are never deleted.

Sameday and easybox are trademarks of their respective owners. This module is not affiliated with or endorsed by Sameday.