VibeFox ShipStation for Adobe Commerce — Hilfe

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 extension.

ShipStation account: connect your carriers in ShipStation (Settings > Shipping > Carriers), then copy the API Key and API Secret from ShipStation > Settings > Account > API Settings. API access depends on your ShipStation plan. If the page is not available, your plan does not include API access. The module uses ShipStation API V1 (API Key and API Secret). ShipStation API V2 accounts with a single API key are not supported. Without keys, only the fallback prices are used.

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-shipstation-shipping. Without Composer: unpack the ZIP file into app/code/Vibefox/ShipstationShipping/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_ShipstationShipping 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 ShipStation. 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. Paste the API key and API secret, enter the ship-from postal code (or leave it empty to use the origin of your store) and click Save Config. Saved account check now lists the carrier codes of your account. Enter the one(s) you want in Carrier codes. If the base currency of your store is not the currency of your ShipStation account, set Account currency and Exchange rate. Optionally fill in the fallback prices. Set Enable to Yes and click Save Config again.

The module adds the ShipStation shipping method to Magento. Customers see it as ShipStation - Courier delivery (method title and method name). It is off after installation (Enable = No).

Configuration

All settings are in Stores > Configuration > Sales > Delivery Methods > VibeFox ShipStation, 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. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page and clears the cached ShipStation rates. Amounts accept "9.99" and "9,99".

Every Save Config on the Delivery Methods page also checks the saved API key and secret with ShipStation, even while Enable is No. The result is stored and shown in Saved account check: the date and time (UTC) and OK: with the carriers connected to your account, for example "stamps_com (Stamps.com); ups_walleted (UPS by ShipStation);", or Failed: with the reason. Opening the page does not contact ShipStation.

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 characters or with one of the characters < > ; = # { }; a Sort order that is not a whole number; a number field (Exchange rate, Other countries, Free shipping from, Minimum subtotal, the weight limits) that does not contain a number of 0 or more; a price in the country table that is not a non-negative number; a Minimum weight greater than the Maximum weight.

While Enable is Yes, warnings after saving tell you when live rates cannot work: API key or secret is empty; only fallback prices are used. (or … and no fallback prices are set; the method is hidden.), No carrier code is configured, Ship-from postal code is empty, Set the exchange rate when the account currency differs from the base currency., Carrier list check failed. with the reason, and Unknown carrier codes: for codes that are not connected to your account. The warnings are shown only while the method is enabled, because the Delivery Methods page is shared by all shipping methods.

General

Enable: shows or hides ShipStation at checkout. Default: No.

Method title: the carrier name shown in the cart and at checkout. Default: ShipStation. Required, at most 64 characters.

Method name: shown after the method title, as "Method title - Method name". Default: Courier delivery. Required, at most 64 characters.

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

ShipStation API V1 account

API key: the API Key from ShipStation > Settings > Account > API Settings. It is sent only to ShipStation and never written to the log. Magento stores it encrypted and shows only a mask after saving. Leave the mask as it is to keep the saved key, type a new value to change it. To delete the saved key, clear the field and click Save Config. Removing the API key also removes the API secret. Only the fallback prices are used then.

API secret: the API Secret from the same page. It is stored and changed the same way as the key.

Carrier codes: one or more ShipStation carrier codes, comma separated, for example stamps_com, ups_walleted. Take them from Saved account check. Up to 5 codes are used, with one API request per carrier. If you enter more, only the first 5 unique codes are kept and Magento shows ShipStation: only the first 5 carrier codes are used; other valid settings were saved. The cheapest rate of these carriers is shown.

Allowed service codes: optional, comma separated ShipStation service codes, for example usps_priority_mail, ups_ground. Leave it empty to use all services. The cheapest allowed service across the configured carriers is shown.

Package code: one code. "package" (the default) rates your own box and leaves out carrier envelopes and flat rate boxes. Leave it empty to rate every package type the carrier offers.

Saved account check: read-only, the result of the last save for the current key and secret (see above). Without a check for these credentials it says No account check for the current credentials. Save settings to check the account.

Ship from

Postal / ZIP code: the ship-from postal code, required for live rates. ShipStation rates from the postal code only, and it must be in the country of your ShipStation account. Leave it empty to use ZIP/Postal Code from Stores > Configuration > Sales > Shipping Settings > Origin.

Rates

Parcels: how the cart is sent to ShipStation.

Account currency: the currency ShipStation returns rates in: USD, CAD, GBP, AUD, NZD or EUR. Default: USD.

Exchange rate: the value of one unit of the account currency in the base currency of your store, for example 0.92. Needed only when the base currency differs from the account currency. Zero or empty disables live rates in that case, and the fallback prices apply. Exchange rates are not updated automatically.

Fallback prices (used when there is no live rate: no API keys, ShipStation unreachable, no carrier rate for the address; in the base currency of your store, tax excluded)

Price per country and weight: a table with a Country, a Base price and the size columns by parcel weight: XS up to 1 kg, S up to 2 kg, M up to 3 kg, L up to 5 kg and XL over 5 kg. The sizes are always in kg. Click Add country to add a row and Delete to remove one. An empty or zero size uses the base price. A base price of 0 means free shipping. The row * All other countries applies to countries without their own row. Rows without any price are removed on save; if a country is entered twice, the last row is kept.

Other countries: the price when the table has no price for the country. If the table and Other countries are both empty, the method is hidden when there is no live rate.

Conditions

Free shipping from: delivery is free if the cart subtotal (products that need shipping, after discounts, before tax, in the base currency) is at least this amount. No request goes to ShipStation. Leave it empty to turn it off.

Minimum subtotal: show the method only if the cart subtotal is at least this amount. Leave it empty to always show it.

Minimum weight (store unit): the minimum cart weight to show the method. Empty or zero means no minimum.

Maximum weight (store unit): hide the method if the cart is heavier. Empty or zero means no maximum.

The weight limits use the weight unit of your store (Stores > Configuration > General > General > Locale Options > Weight Unit, lbs or kgs). For ShipStation the weights are converted to grams. Magento products have no standard dimensions, so no dimensions are sent and parcels are rated by weight only.

Countries (below the Conditions section)

Ship to Applicable Countries: All Allowed Countries offers ShipStation for every country your store allows, Specific Countries only for the countries below.

Ship to Specific Countries: the destination countries for Specific Countries.

Advanced

Debug log: writes rate requests and calculations to var/log/vfd_shst_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 key and secret, the encoded authentication and the destination postcode and city are never logged. The log starts a new file at 5 MB.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the ShipStation settings and the log (see Uninstall). The license key, the cached rates and the account check are always removed. The service saved with placed orders is never deleted.

Debug log viewer: shows the size and the latest entries of the log, or The log is empty. Click Clear log to empty it.

Tax on shipping is not a setting of the module. If your store taxes shipping, set Stores > Configuration > Sales > Tax > Tax Classes > Tax Class for Shipping. ShipStation rates do not include sales tax.

How it works at checkout

At the shipping step Magento asks the module for the ShipStation price. Only products that need shipping count: virtual and downloadable products add no weight and are not included in the subtotal. The module first checks the countries, the cart weight and Minimum subtotal. If Free shipping from applies, the price is 0 and no request goes to ShipStation. A Magento cart price rule with free shipping also makes the price 0, without a request.

The module then sends ShipStation the ship-from postal code, the destination country, state, city and postcode and the parcel weight. No request is made before the customer has entered a postcode; countries without postcodes get the fallback prices. ShipStation is asked once per carrier code. The module uses the cheapest allowed rate, converted from the account currency to your base currency and rounded to 2 decimals. Magento then shows it in the customer's currency and adds tax on shipping if your store charges it.

Each answer is cached for 1 hour. When ShipStation answers without a usable rate, the answer is remembered for 10 minutes. When ShipStation rejects the keys, is unreachable or returns a server error, requests are paused for 5 minutes. After a rate limit, the pause follows ShipStation's reset time (10 to 120 seconds). The request timeout is 12 seconds. The Magento cron removes expired cache entries.

If there is no live rate, the price comes from the fallback table, then from Other countries. If neither applies, the method is hidden. The customer never sees ShipStation error texts. Details go to the debug log.

The module calculates rates only. It does not buy labels, create ShipStation orders or shipments, track parcels or handle returns. There are no pickup points, no choice between several services at checkout, no delivery time estimate, no address validation, insurance, signature confirmation, packing into several parcels or rate markup.

Orders

When an order is placed with a live ShipStation rate, the chosen service is saved with the order. On the admin order page (Sales > Orders > View, Information tab) the ShipStation shipping block shows the Service, for example "USPS Ground Advantage - Package", and the Live rate in base currency, so you can create the matching label in ShipStation. With One parcel per item the services of all items are listed. Later recalculations do not change it. Orders placed with a fallback price or free shipping have no ShipStation block. The block is also shown for older orders and when the module is switched off.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox ShipStation is the first row of the VibeFox ShipStation 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-shipstation 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 ShipStation method is not shown to customers at checkout and no rate is calculated. 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

ShipStation does not appear at checkout: check that the license is active and Enable is Yes for the website of the store. Check Ship to Applicable Countries and Ship to Specific Countries, the weight limits and Minimum subtotal. Without a live rate, check that the country, * All other countries or Other countries has a price.

The checkout shows the fallback price instead of the ShipStation rate: set Enable to Yes, click Save Config and read the warnings (keys, carrier code, ship-from postal code, exchange rate, account check). Turn on Debug log, reload the checkout and look at Debug log viewer in the Advanced section. The customer's postcode is required. No request is made before it is entered.

Which carrier code to enter: save the settings with the key and secret. Saved account check lists the carrier codes of your account. Use one or more of them.

The account check failed: Saved account check shows the reason after Failed:. Check the API key and API secret, then click Save Config to repeat the check.

The rate differs from ShipStation: the parcel is rated by the cart weight only, without dimensions. Rates are cached for 1 hour. Click Save Config on the Delivery Methods page to clear the cache.

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 and the settings stay. To remove the data, uninstall the module with the Magento command:

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

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

The license key, the license status, the cached rates, the account check and the rates of carts that were not ordered are always removed. If Remove data on uninstall is Yes, the ShipStation settings and the log are removed too. If it is No, the settings and the log are kept for a re-install. The service saved with placed orders stays in both cases.

ShipStation is a trademark of its respective owner. This module is not affiliated with or endorsed by ShipStation.